summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASRange_new.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/ASRange_new.3')
-rw-r--r--src/lib/libcrypto/man/ASRange_new.3410
1 files changed, 0 insertions, 410 deletions
diff --git a/src/lib/libcrypto/man/ASRange_new.3 b/src/lib/libcrypto/man/ASRange_new.3
deleted file mode 100644
index dc58c98e58..0000000000
--- a/src/lib/libcrypto/man/ASRange_new.3
+++ /dev/null
@@ -1,410 +0,0 @@
1.\" $OpenBSD: ASRange_new.3,v 1.8 2023/10/11 12:06:11 tb Exp $
2.\"
3.\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: October 11 2023 $
18.Dt ASRANGE_NEW 3
19.Os
20.Sh NAME
21.Nm ASRange_new ,
22.Nm ASRange_free ,
23.Nm d2i_ASRange ,
24.Nm i2d_ASRange ,
25.Nm ASIdOrRange_new ,
26.Nm ASIdOrRange_free ,
27.Nm d2i_ASIdOrRange ,
28.Nm i2d_ASIdOrRange ,
29.Nm ASIdentifierChoice_new ,
30.Nm ASIdentifierChoice_free ,
31.Nm d2i_ASIdentifierChoice ,
32.Nm i2d_ASIdentifierChoice
33.Nd RFC 3779 autonomous system identifiers and ranges
34.Sh SYNOPSIS
35.In openssl/x509v3.h
36.Ft "ASRange *"
37.Fn ASRange_new void
38.Ft void
39.Fn ASRange_free "ASRange *asrange"
40.Ft ASRange *
41.Fo d2i_ASRange
42.Fa "ASRange **asrange"
43.Fa "const unsigned char **der_in"
44.Fa "long length"
45.Fc
46.Ft int
47.Fo i2d_ASRange
48.Fa "ASRange *asrange"
49.Fa "unsigned char **der_out"
50.Fc
51.Ft "ASIdOrRange *"
52.Fn ASIdOrRange_new void
53.Ft void
54.Fn ASIdOrRange_free "ASIdOrRange *aor"
55.Ft ASIdOrRange *
56.Fo d2i_ASIdOrRange
57.Fa "ASIdOrRange **aor"
58.Fa "const unsigned char **der_in"
59.Fa "long length"
60.Fc
61.Ft int
62.Fo i2d_ASIdOrRange
63.Fa "ASIdOrRange *aor"
64.Fa "unsigned char **der_out"
65.Fc
66.Ft "ASIdentifierChoice *"
67.Fn ASIdentifierChoice_new void
68.Ft void
69.Fn ASIdentifierChoice_free "ASIdentifierChoice *aic"
70.Ft ASIdentifierChoice *
71.Fo d2i_ASIdentifierChoice
72.Fa "ASIdentifierChoice **aic"
73.Fa "const unsigned char **der_in"
74.Fa "long length"
75.Fc
76.Ft int
77.Fo i2d_ASIdentifierChoice
78.Fa "ASIdentifierChoice *aic"
79.Fa "unsigned char **der_out"
80.Fc
81.Sh DESCRIPTION
82.Vt ASRange ,
83.Vt ASIdOrRange ,
84and
85.Vt ASIdentifierChoice
86are building blocks of the
87.Vt ASIdentifiers
88type representing the RFC 3779
89autonomous system identifier delegation extension.
90.Pp
91All
92.Vt ASN1_INTEGER Ns s
93in this manual must be representable as unsigned 32-bit integers.
94The API performs no corresponding checks.
95An
96.Vt ASN1_INTEGER
97can be set using
98.Xr ASN1_INTEGER_set_uint64 3 .
99.Pp
100The
101.Vt ASRange
102type defined in RFC 3779 section 3.2.3.8 is implemented as
103.Bd -literal -offset indent
104typedef struct ASRange_st {
105 ASN1_INTEGER *min;
106 ASN1_INTEGER *max;
107} ASRange;
108.Ed
109.Pp
110It represents the closed range [min,max] of AS identifiers between
111.Fa min
112and
113.Fa max ,
114where
115.Fa min
116should be strictly smaller than
117.Fa max .
118.Pp
119.Fn ASRange_new
120allocates a new
121.Vt ASRange
122object with allocated, empty
123.Fa min
124and
125.Fa max ,
126thus representing the invalid range [0,0].
127.Pp
128.Fn ASRange_free
129frees
130.Fa asrange
131including any data contained in it.
132If
133.Fa asrange
134is
135.Dv NULL ,
136no action occurs.
137.Pp
138The
139.Vt ASIdOrRange
140type defined in RFC 3779 section 3.2.3.5 is implemented as
141.Bd -literal -offset indent
142typedef struct ASIdOrRange_st {
143 int type;
144 union {
145 ASN1_INTEGER *id;
146 ASRange *range;
147 } u;
148} ASIdOrRange;
149.Ed
150.Pp
151representing an individual AS identifier or a range.
152When populating an
153.Vt ASIdOrRange
154object by hand, its
155.Fa type
156should be set to
157.Dv ASIdOrRange_id
158or
159.Dv ASIdOrRange_range
160to indicate which member of the union
161.Fa u
162is valid.
163.Pp
164.Fn ASIdOrRange_new
165returns a new
166.Vt ASIdOrRange
167object with invalid type and
168.Dv NULL
169members of the union
170.Fa u .
171.Pp
172.Fn ASIdOrRange_free
173frees
174.Fa aor
175including any data contained in it,
176provided
177.Fa type
178is set correctly.
179If
180.Fa asrange
181is
182.Dv NULL ,
183no action occurs.
184.Pp
185In order to express a list of AS identifiers and ranges,
186RFC 3779 section 3.2.3.4
187uses an ASN.1 SEQUENCE,
188which is implemented via a
189.Xr STACK_OF 3
190construction over
191.Vt ASIdOrRange :
192.Bd -literal -offset indent
193typedef STACK_OF(ASIdOrRange) ASIdOrRanges;
194.Ed
195.Pp
196Since an
197.Vt ASIdOrRanges
198object should be sorted in a specific way (see
199.Xr X509v3_asid_canonize 3 Ns ),
200a comparison function is needed for a correct instantiation
201with
202.Xr sk_new 3 .
203The
204.Fn ASIdOrRange_cmp
205function is not directly exposed and not easily accessible
206from outside the library,
207and it is non-trivial to implement.
208It is therefore discouraged to use
209.Vt ASIdOrRanges
210objects that are not part of an
211.Vt ASIdentifiers
212object.
213.Pp
214The
215.Dq inherit
216marker from RFC 3779 section 3.2.3.3 is implemented as
217.Vt ASN1_NULL .
218It has no dedicated type or API and can be instantiated with
219.Xr ASN1_NULL_new 3 .
220.Pp
221The
222.Vt ASIdentifierChoice
223type defined in RFC 3779 section 3.2.3.2 is implemented as
224.Bd -literal -offset indent
225typedef struct ASIdentifierChoice_st {
226 int type;
227 union {
228 ASN1_NULL *inherit;
229 ASIdOrRanges *asIdsOrRanges;
230 } u;
231} ASIdentifierChoice;
232.Ed
233.Pp
234where the
235.Fa type
236member should be set to
237.Dv ASIdentifierChoice_inherit
238or
239.Dv ASIdentifierChoice_asIdsOrRanges
240to indicate whether a given
241.Vt ASIdentifierChoice
242object represents an inherited list or an explicit list.
243.Pp
244.Fn ASIdentifierChoice_new
245returns a new
246.Vt ASIdentifierChoice
247object with invalid type and
248.Dv NULL
249members of the union
250.Fa u .
251.Pp
252.Fn ASIdentifierChoice_free
253frees
254.Fa aic
255including any data contained in it,
256provided
257.Fa type
258is set correctly.
259.Pp
260The
261.Vt ASIdentifiers
262type defined in RFC 3779 section 3.2.3.1 is implemented as
263.Bd -literal -offset indent
264typedef struct ASIdentifiers_st {
265 ASIdentifierChoice *asnum;
266 ASIdentifierChoice *rdi;
267} ASIdentifiers;
268.Ed
269.Pp
270It should be instantiated with
271.Xr ASIdentifiers_new 3
272and populated with
273.Xr X509v3_asid_add_id_or_range 3 .
274.Pp
275.Fn d2i_ASRange ,
276.Fn i2d_ASRange ,
277.Fn d2i_ASIdOrRange ,
278.Fn i2d_ASIdOrRange ,
279.Fn d2i_ASIdentifierChoice ,
280and
281.Fn i2d_ASIdentifierChoice
282decode and encode ASN.1
283.Vt ASRange ,
284.Vt ASIdOrRange ,
285and
286.Vt ASIdentifierChoice
287objects.
288For details about the semantics, examples, caveats, and bugs, see
289.Xr ASN1_item_d2i 3 .
290In order for the encoding produced by
291.Fn i2d_ASRange
292to be correct,
293.Fa min
294must be strictly less than
295.Fa max .
296Similarly for
297.Fn i2d_ASIdOrRange
298and an
299.Fa ASIdOrRange
300object of
301.Fa type
302.Dv ASIdOrRange_range .
303.Sh RETURN VALUES
304.Fn ASRange_new
305returns a new
306.Vt ASRange
307object with allocated, empty members, or
308.Dv NULL
309if an error occurs.
310.Pp
311.Fn ASIdOrRange_new
312returns a new, empty
313.Vt ASIdOrRange
314object or
315.Dv NULL
316if an error occurs.
317.Pp
318.Fn ASIdentifierChoice_new
319returns a new, empty
320.Vt ASIdentifierChoice
321object or
322.Dv NULL
323if an error occurs.
324.Pp
325The decoding functions
326.Fn d2i_ASRange ,
327.Fn d2i_ASIdOrRange ,
328and
329.Fn d2i_ASIdentifierChoice
330return an
331.Vt ASRange ,
332an
333.Vt ASIdOrRange ,
334or an
335.Vt ASIdentifierChoice ,
336object, respectively,
337or
338.Dv NULL
339if an error occurs.
340.Pp
341The encoding functions
342.Fn i2d_ASRange ,
343.Fn i2d_ASIdOrRange ,
344and
345.Fn i2d_ASIdentifierChoice
346return the number of bytes successfully encoded
347or a value <= 0 if an error occurs.
348.Sh SEE ALSO
349.Xr ASIdentifiers_new 3 ,
350.Xr ASN1_INTEGER_set_uint64 3 ,
351.Xr crypto 3 ,
352.Xr IPAddressRange_new 3 ,
353.Xr s2i_ASN1_INTEGER 3 ,
354.Xr STACK_OF 3 ,
355.Xr X509_new 3 ,
356.Xr X509v3_asid_add_id_or_range 3
357.Sh STANDARDS
358RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
359.Bl -dash -compact
360.It
361section 3.2.3: Syntax
362.It
363section 3.2.3.1: Type ASIdentifiers
364.It
365section 3.2.3.2: Elements asnum, rdi, and Type ASIdentifierChoice
366.It
367section 3.2.3.3: Element inherit
368.It
369section 3.2.3.4: Element asIdsOrRanges
370.It
371section 3.2.3.5: Type ASIdOrRange
372.It
373section 3.2.3.6: Element id
374.It
375section 3.2.3.7: Element range
376.It
377section 3.2.3.8: Type ASRange
378.It
379section 3.2.3.9: Elements min and max
380.El
381.Sh HISTORY
382These functions first appeared in OpenSSL 0.9.8e
383and have been available since
384.Ox 7.1 .
385.Sh BUGS
386An
387.Fn ASIdOrRanges_new
388function that installs the correct comparison function
389on the stack of
390.Vt ASIdOrRange
391should have been part of the API to make it usable.
392.Pp
393.Fn ASIdentifierChoice_new
394is of very limited use because
395.Fn ASIdOrRanges_new
396is missing.
397.Pp
398There is no way of ensuring that an
399.Vt ASIdOrRanges
400object is in canonical form unless it is part of an
401.Vt ASIdentifiers
402object.
403It is therefore difficult to guarantee that the output of
404.Fn i2d_ASIdentifierChoice
405is conformant.
406.Pp
407RFC 3779 3.2.3.4 has
408.Dq Fa asIdsOrRanges
409while its type in this implementation is
410.Vt ASIdOrRanges .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-12-23 15:17:17 +0000