From eb8dd9dca1228af0cd132f515509051ecfabf6f6 Mon Sep 17 00:00:00 2001 From: cvs2svn Date: Mon, 14 Apr 2025 17:32:06 +0000 Subject: This commit was manufactured by cvs2git to create tag 'tb_20250414'. --- src/lib/libcrypto/man/ASRange_new.3 | 410 ------------------------------------ 1 file changed, 410 deletions(-) delete mode 100644 src/lib/libcrypto/man/ASRange_new.3 (limited to 'src/lib/libcrypto/man/ASRange_new.3') 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 @@ -.\" $OpenBSD: ASRange_new.3,v 1.8 2023/10/11 12:06:11 tb Exp $ -.\" -.\" Copyright (c) 2023 Theo Buehler -.\" -.\" Permission to use, copy, modify, and distribute this software for any -.\" purpose with or without fee is hereby granted, provided that the above -.\" copyright notice and this permission notice appear in all copies. -.\" -.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES -.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF -.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR -.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES -.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN -.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF -.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. -.\" -.Dd $Mdocdate: October 11 2023 $ -.Dt ASRANGE_NEW 3 -.Os -.Sh NAME -.Nm ASRange_new , -.Nm ASRange_free , -.Nm d2i_ASRange , -.Nm i2d_ASRange , -.Nm ASIdOrRange_new , -.Nm ASIdOrRange_free , -.Nm d2i_ASIdOrRange , -.Nm i2d_ASIdOrRange , -.Nm ASIdentifierChoice_new , -.Nm ASIdentifierChoice_free , -.Nm d2i_ASIdentifierChoice , -.Nm i2d_ASIdentifierChoice -.Nd RFC 3779 autonomous system identifiers and ranges -.Sh SYNOPSIS -.In openssl/x509v3.h -.Ft "ASRange *" -.Fn ASRange_new void -.Ft void -.Fn ASRange_free "ASRange *asrange" -.Ft ASRange * -.Fo d2i_ASRange -.Fa "ASRange **asrange" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_ASRange -.Fa "ASRange *asrange" -.Fa "unsigned char **der_out" -.Fc -.Ft "ASIdOrRange *" -.Fn ASIdOrRange_new void -.Ft void -.Fn ASIdOrRange_free "ASIdOrRange *aor" -.Ft ASIdOrRange * -.Fo d2i_ASIdOrRange -.Fa "ASIdOrRange **aor" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_ASIdOrRange -.Fa "ASIdOrRange *aor" -.Fa "unsigned char **der_out" -.Fc -.Ft "ASIdentifierChoice *" -.Fn ASIdentifierChoice_new void -.Ft void -.Fn ASIdentifierChoice_free "ASIdentifierChoice *aic" -.Ft ASIdentifierChoice * -.Fo d2i_ASIdentifierChoice -.Fa "ASIdentifierChoice **aic" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_ASIdentifierChoice -.Fa "ASIdentifierChoice *aic" -.Fa "unsigned char **der_out" -.Fc -.Sh DESCRIPTION -.Vt ASRange , -.Vt ASIdOrRange , -and -.Vt ASIdentifierChoice -are building blocks of the -.Vt ASIdentifiers -type representing the RFC 3779 -autonomous system identifier delegation extension. -.Pp -All -.Vt ASN1_INTEGER Ns s -in this manual must be representable as unsigned 32-bit integers. -The API performs no corresponding checks. -An -.Vt ASN1_INTEGER -can be set using -.Xr ASN1_INTEGER_set_uint64 3 . -.Pp -The -.Vt ASRange -type defined in RFC 3779 section 3.2.3.8 is implemented as -.Bd -literal -offset indent -typedef struct ASRange_st { - ASN1_INTEGER *min; - ASN1_INTEGER *max; -} ASRange; -.Ed -.Pp -It represents the closed range [min,max] of AS identifiers between -.Fa min -and -.Fa max , -where -.Fa min -should be strictly smaller than -.Fa max . -.Pp -.Fn ASRange_new -allocates a new -.Vt ASRange -object with allocated, empty -.Fa min -and -.Fa max , -thus representing the invalid range [0,0]. -.Pp -.Fn ASRange_free -frees -.Fa asrange -including any data contained in it. -If -.Fa asrange -is -.Dv NULL , -no action occurs. -.Pp -The -.Vt ASIdOrRange -type defined in RFC 3779 section 3.2.3.5 is implemented as -.Bd -literal -offset indent -typedef struct ASIdOrRange_st { - int type; - union { - ASN1_INTEGER *id; - ASRange *range; - } u; -} ASIdOrRange; -.Ed -.Pp -representing an individual AS identifier or a range. -When populating an -.Vt ASIdOrRange -object by hand, its -.Fa type -should be set to -.Dv ASIdOrRange_id -or -.Dv ASIdOrRange_range -to indicate which member of the union -.Fa u -is valid. -.Pp -.Fn ASIdOrRange_new -returns a new -.Vt ASIdOrRange -object with invalid type and -.Dv NULL -members of the union -.Fa u . -.Pp -.Fn ASIdOrRange_free -frees -.Fa aor -including any data contained in it, -provided -.Fa type -is set correctly. -If -.Fa asrange -is -.Dv NULL , -no action occurs. -.Pp -In order to express a list of AS identifiers and ranges, -RFC 3779 section 3.2.3.4 -uses an ASN.1 SEQUENCE, -which is implemented via a -.Xr STACK_OF 3 -construction over -.Vt ASIdOrRange : -.Bd -literal -offset indent -typedef STACK_OF(ASIdOrRange) ASIdOrRanges; -.Ed -.Pp -Since an -.Vt ASIdOrRanges -object should be sorted in a specific way (see -.Xr X509v3_asid_canonize 3 Ns ), -a comparison function is needed for a correct instantiation -with -.Xr sk_new 3 . -The -.Fn ASIdOrRange_cmp -function is not directly exposed and not easily accessible -from outside the library, -and it is non-trivial to implement. -It is therefore discouraged to use -.Vt ASIdOrRanges -objects that are not part of an -.Vt ASIdentifiers -object. -.Pp -The -.Dq inherit -marker from RFC 3779 section 3.2.3.3 is implemented as -.Vt ASN1_NULL . -It has no dedicated type or API and can be instantiated with -.Xr ASN1_NULL_new 3 . -.Pp -The -.Vt ASIdentifierChoice -type defined in RFC 3779 section 3.2.3.2 is implemented as -.Bd -literal -offset indent -typedef struct ASIdentifierChoice_st { - int type; - union { - ASN1_NULL *inherit; - ASIdOrRanges *asIdsOrRanges; - } u; -} ASIdentifierChoice; -.Ed -.Pp -where the -.Fa type -member should be set to -.Dv ASIdentifierChoice_inherit -or -.Dv ASIdentifierChoice_asIdsOrRanges -to indicate whether a given -.Vt ASIdentifierChoice -object represents an inherited list or an explicit list. -.Pp -.Fn ASIdentifierChoice_new -returns a new -.Vt ASIdentifierChoice -object with invalid type and -.Dv NULL -members of the union -.Fa u . -.Pp -.Fn ASIdentifierChoice_free -frees -.Fa aic -including any data contained in it, -provided -.Fa type -is set correctly. -.Pp -The -.Vt ASIdentifiers -type defined in RFC 3779 section 3.2.3.1 is implemented as -.Bd -literal -offset indent -typedef struct ASIdentifiers_st { - ASIdentifierChoice *asnum; - ASIdentifierChoice *rdi; -} ASIdentifiers; -.Ed -.Pp -It should be instantiated with -.Xr ASIdentifiers_new 3 -and populated with -.Xr X509v3_asid_add_id_or_range 3 . -.Pp -.Fn d2i_ASRange , -.Fn i2d_ASRange , -.Fn d2i_ASIdOrRange , -.Fn i2d_ASIdOrRange , -.Fn d2i_ASIdentifierChoice , -and -.Fn i2d_ASIdentifierChoice -decode and encode ASN.1 -.Vt ASRange , -.Vt ASIdOrRange , -and -.Vt ASIdentifierChoice -objects. -For details about the semantics, examples, caveats, and bugs, see -.Xr ASN1_item_d2i 3 . -In order for the encoding produced by -.Fn i2d_ASRange -to be correct, -.Fa min -must be strictly less than -.Fa max . -Similarly for -.Fn i2d_ASIdOrRange -and an -.Fa ASIdOrRange -object of -.Fa type -.Dv ASIdOrRange_range . -.Sh RETURN VALUES -.Fn ASRange_new -returns a new -.Vt ASRange -object with allocated, empty members, or -.Dv NULL -if an error occurs. -.Pp -.Fn ASIdOrRange_new -returns a new, empty -.Vt ASIdOrRange -object or -.Dv NULL -if an error occurs. -.Pp -.Fn ASIdentifierChoice_new -returns a new, empty -.Vt ASIdentifierChoice -object or -.Dv NULL -if an error occurs. -.Pp -The decoding functions -.Fn d2i_ASRange , -.Fn d2i_ASIdOrRange , -and -.Fn d2i_ASIdentifierChoice -return an -.Vt ASRange , -an -.Vt ASIdOrRange , -or an -.Vt ASIdentifierChoice , -object, respectively, -or -.Dv NULL -if an error occurs. -.Pp -The encoding functions -.Fn i2d_ASRange , -.Fn i2d_ASIdOrRange , -and -.Fn i2d_ASIdentifierChoice -return the number of bytes successfully encoded -or a value <= 0 if an error occurs. -.Sh SEE ALSO -.Xr ASIdentifiers_new 3 , -.Xr ASN1_INTEGER_set_uint64 3 , -.Xr crypto 3 , -.Xr IPAddressRange_new 3 , -.Xr s2i_ASN1_INTEGER 3 , -.Xr STACK_OF 3 , -.Xr X509_new 3 , -.Xr X509v3_asid_add_id_or_range 3 -.Sh STANDARDS -RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: -.Bl -dash -compact -.It -section 3.2.3: Syntax -.It -section 3.2.3.1: Type ASIdentifiers -.It -section 3.2.3.2: Elements asnum, rdi, and Type ASIdentifierChoice -.It -section 3.2.3.3: Element inherit -.It -section 3.2.3.4: Element asIdsOrRanges -.It -section 3.2.3.5: Type ASIdOrRange -.It -section 3.2.3.6: Element id -.It -section 3.2.3.7: Element range -.It -section 3.2.3.8: Type ASRange -.It -section 3.2.3.9: Elements min and max -.El -.Sh HISTORY -These functions first appeared in OpenSSL 0.9.8e -and have been available since -.Ox 7.1 . -.Sh BUGS -An -.Fn ASIdOrRanges_new -function that installs the correct comparison function -on the stack of -.Vt ASIdOrRange -should have been part of the API to make it usable. -.Pp -.Fn ASIdentifierChoice_new -is of very limited use because -.Fn ASIdOrRanges_new -is missing. -.Pp -There is no way of ensuring that an -.Vt ASIdOrRanges -object is in canonical form unless it is part of an -.Vt ASIdentifiers -object. -It is therefore difficult to guarantee that the output of -.Fn i2d_ASIdentifierChoice -is conformant. -.Pp -RFC 3779 3.2.3.4 has -.Dq Fa asIdsOrRanges -while its type in this implementation is -.Vt ASIdOrRanges . -- cgit v1.2.3-55-g6feb