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/IPAddressRange_new.3 | 525 ----------------------------- 1 file changed, 525 deletions(-) delete mode 100644 src/lib/libcrypto/man/IPAddressRange_new.3 (limited to 'src/lib/libcrypto/man/IPAddressRange_new.3') diff --git a/src/lib/libcrypto/man/IPAddressRange_new.3 b/src/lib/libcrypto/man/IPAddressRange_new.3 deleted file mode 100644 index a812107cdf..0000000000 --- a/src/lib/libcrypto/man/IPAddressRange_new.3 +++ /dev/null @@ -1,525 +0,0 @@ -.\" $OpenBSD: IPAddressRange_new.3,v 1.9 2023/10/03 09:58:06 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 3 2023 $ -.Dt IPADDRESSRANGE_NEW 3 -.Os -.Sh NAME -.Nm IPAddressRange_new , -.Nm IPAddressRange_free , -.Nm d2i_IPAddressRange , -.Nm i2d_IPAddressRange , -.Nm IPAddressOrRange_new , -.Nm IPAddressOrRange_free , -.Nm d2i_IPAddressOrRange , -.Nm i2d_IPAddressOrRange , -.Nm IPAddressChoice_new , -.Nm IPAddressChoice_free , -.Nm d2i_IPAddressChoice , -.Nm i2d_IPAddressChoice , -.Nm IPAddressFamily_new , -.Nm IPAddressFamily_free , -.Nm d2i_IPAddressFamily , -.Nm i2d_IPAddressFamily -.Nd RFC 3779 IP address prefixes and ranges -.Sh SYNOPSIS -.In openssl/x509v3.h -.Ft "IPAddressRange *" -.Fn IPAddressRange_new void -.Ft void -.Fn IPAddressRange_free "IPAddressRange *range" -.Ft IPAddressRange * -.Fo d2i_IPAddressRange -.Fa "IPAddressRange **range" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_IPAddressRange -.Fa "IPAddressRange *range" -.Fa "unsigned char **der_out" -.Fc -.Ft "IPAddressOrRange *" -.Fn IPAddressOrRange_new void -.Ft void -.Fn IPAddressOrRange_free "IPAddressOrRange *aor" -.Ft IPAddressOrRange * -.Fo d2i_IPAddressOrRange -.Fa "IPAddressOrRange **aor" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_IPAddressOrRange -.Fa "IPAddressOrRange *aor" -.Fa "unsigned char **der_out" -.Fc -.Ft "IPAddressChoice *" -.Fn IPAddressChoice_new void -.Ft void -.Fn IPAddressChoice_free "IPAddressChoice *ac" -.Ft IPAddressChoice * -.Fo d2i_IPAddressChoice -.Fa "IPAddressChoice **ac" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_IPAddressChoice -.Fa "IPAddressChoice *ac" -.Fa "unsigned char **der_out" -.Fc -.Ft "IPAddressFamily *" -.Fn IPAddressFamily_new void -.Ft void -.Fn IPAddressFamily_free "IPAddressFamily *af" -.Ft IPAddressFamily * -.Fo d2i_IPAddressFamily -.Fa "IPAddressFamily **af" -.Fa "const unsigned char **der_in" -.Fa "long length" -.Fc -.Ft int -.Fo i2d_IPAddressFamily -.Fa "IPAddressFamily *af" -.Fa "unsigned char **der_out" -.Fc -.Sh DESCRIPTION -.Vt IPAddressRange , -.Vt IPAddressOrRange , -.Vt IPAddressChoice , -and -.Vt IPAddressFamily -are building blocks of the -.Vt IPAddrBlocks -type representing the RFC 3779 IP address delegation extension. -.Pp -Per RFC 3779, section 2.1.1, -an IPv4 or an IPv6 address is encoded in network byte order in an -ASN.1 BIT STRING of bit size 32 or 128 bits, respectively. -The bit size of a prefix is its prefix length; -all insignificant zero bits are omitted -from the encoding. -Per section 2.1.2, -an address range is expressed as a pair of BIT STRINGs -where all the least significant zero bits of the lower bound -and all the least significant one bits of the upper bound are omitted. -.Pp -The library provides no API for directly converting an IP address or -prefix (in any form) to and from an -.Vt ASN1_BIT_STRING . -It also provides no API for directly handling ranges. -The -.Vt ASN1_BIT_STRING -internals are subtle and directly manipulating them in the -context of the RFC 3779 API is discouraged. -The bit size of an -.Vt ASN1_BIT_STRING -representing an IP address prefix or range is eight times its -.Fa length -member minus the lowest three bits of its -.Fa flags , -provided the -.Dv ASN1_STRING_FLAG_BITS_LEFT -flag is set. -.Pp -The -.Vt IPAddressRange -type defined in RFC 3779 section 2.2.3.9 is implemented as -.Bd -literal -offset indent -typedef struct IPAddressRange_st { - ASN1_BIT_STRING *min; - ASN1_BIT_STRING *max; -} IPAddressRange; -.Ed -.Pp -It represents the closed range [min,max] of IP addresses between -.Fa min -and -.Fa max , -where -.Fa min -should be strictly smaller than -.Fa max -and the range should not be expressible as a prefix. -.Pp -.Fn IPAddressRange_new -allocates a new -.Vt IPAddressRange -object with allocated, empty -.Fa min -and -.Fa max , -thus representing the entire address space invalidly as a non-prefix. -.Pp -.Fn IPAddressRange_free -frees -.Fa range -including any data contained in it. -If -.Fa range -is -.Dv NULL , -no action occurs. -.Pp -There is no dedicated type representing the -.Vt IPAddress -type defined in RFC 3779 section 2.2.3.8. -The API uses -.Vt ASN1_BIT_STRING -for this. -.Pp -The -.Vt IPAddressOrRange -type defined in RFC 3779 section 2.2.3.7 is implemented as -.Bd -literal -offset indent -typedef struct IPAddressOrRange_st { - int type; - union { - ASN1_BIT_STRING *addressPrefix; - IPAddressRange *addressRange; - } u; -} IPAddressOrRange; -.Ed -.Pp -representing an individual address prefix or an address range. -The -.Fa type -member should be set to -.Dv IPAddressOrRange_addressPrefix -or -.Dv IPAddressOrRange_addressRange -to indicate which member of the union -.Fa u -is valid. -.Pp -.Fn IPAddressOrRange_new -returns a new -.Vt IPAddressOrRange -object with invalid type and -.Dv NULL -members of the union -.Fa u . -.Pp -.Fn IPAddressOrRange_free -frees -.Fa aor -including any data contained in it, -provided -.Fa type -is set correctly. -If -.Fa aor -is -.Dv NULL , -no action occurs. -.Pp -In order to express a list of address prefixes and address ranges, -RFC 3779 section 2.2.3.6 -uses an ASN.1 SEQUENCE, -which is implemented via a -.Xr STACK_OF 3 -construction over -.Vt IPAddressOrRange : -.Bd -literal -offset indent -typedef STACK_OF(IPAddressOrRange) IPAddressOrRanges; -.Ed -.Pp -Since an -.Vt IPAddressOrRanges -object should be sorted in a specific way (see -.Xr X509v3_addr_canonize 3 ) , -a comparison function is needed for a correct instantiation -with -.Xr sk_new 3 . -The -.Fn v4IPAddressOrRange_cmp -and -.Fn v6IPAddressOrRange_cmp -functions are not directly exposed and not easily accessible -from outside the library, -and they are non-trivial to implement. -It is therefore discouraged to use -.Vt IPAddressOrRanges -objects that are not part of an -.Vt IPAddrBlocks -object. -.Pp -The -.Dq inherit -marker from RFC 3779 section 2.2.3.5 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 IPAddressChoice -type defined in RFC 3779 section 2.2.3.4 is implemented as -.Bd -literal -offset indent -typedef struct IPAddressChoice_st { - int type; - union { - ASN1_NULL *inherit; - IPAddressOrRanges *addressesOrRanges; - } u; -} IPAddressChoice; -.Ed -.Pp -where the -.Fa type -member should be set to -.Dv IPAddressChoice_inherit -or -.Dv IPAddressChoice_addressesOrRanges -to indicate whether a given -.Vt IPAddressChoice -object represents an inherited list or an explicit list. -.Pp -.Fn IPAddressChoice_new -returns a new -.Vt IPAddressChoice -object with invalid type and -.Dv NULL -members of the union -.Fa u . -.Pp -.Fn IPAddressChoice_free -frees -.Fa ac -including any data contained in it, -provided -.Fa type -is set correctly. -.Pp -The -.Fa addressFamily -element defined in RFC 3779 section 2.2.3.3 is implemented as an -.Vt ASN1_OCTET_STRING -and it contains two or three octets. -The first two octets are always present and represent the -address family identifier (AFI) -in network byte order. -The optional subsequent address family identifier (SAFI) -occupies the third octet. -For IPv4 and IPv6, -.Dv IANA_AFI_IPV4 -and -.Dv IANA_AFI_IPV6 -are predefined. -Other AFIs are not supported by this implementation. -.Pp -The -.Vt IPAddressFamily -type defined in RFC 3779 section 2.2.3.2 is implemented as -.Bd -literal -offset indent -typedef struct IPAddressFamily_st { - ASN1_OCTET_STRING *addressFamily; - IPAddressChoice *ipAddressChoice; -} IPAddressFamily; -.Ed -.Pp -The -.Fa addressFamily -member indicates the address family the -.Fa ipAddressChoice -represents. -.Pp -.Fn IPAddressFamily_new -returns a new -.Vt IPAddressFamily -object with empty -.Fa addressFamily -and invalid -.Fa ipAddressChoice -members. -.Pp -.Fn IPAddressFamily_free -frees -.Fa af -including any data contained in it. -If -.Fa af -is -.Dv NULL , -no action occurs. -.Pp -The -.Vt IPAddrBlocks -type defined in RFC 3779 section 2.2.3.1 -uses an ASN.1 SEQUENCE, -which is implemented via a -.Xr STACK_OF 3 -construction over -.Vt IPAddressFamily : -.Bd -literal -offset indent -typedef STACK_OF(IPAddressFamily) IPAddrBlocks; -.Ed -.Pp -It can be instantiated with -.Fn sk_IPAddressFamily_new_null -and the correct sorting function can be installed with -.Xr X509v3_addr_canonize 3 . -To populate it, use -.Xr X509v3_addr_add_prefix 3 -and related functions. -.Pp -.Fn d2i_IPAddressRange , -.Fn i2d_IPAddressRange , -.Fn d2i_IPAddressOrRange , -.Fn i2d_IPAddressOrRange , -.Fn d2i_IPAddressChoice , -.Fn i2d_IPAddressChoice , -.Fn d2i_IPAddressFamily , -and -.Fn i2d_IPAddressFamily -decode and encode ASN.1 -.Vt IPAddressRange , -.Vt IPAddressOrRange , -.Vt IPAddressChoice , -and -.Vt IPAddressFamily -objects. -For details about the semantics, examples, caveats, and bugs, see -.Xr ASN1_item_d2i 3 . -There is no easy way of ensuring that the encodings generated by -these functions are correct, unless they are applied to objects -that are part of a canonical -.Vt IPAddrBlocks -structure, see -.Xr X509v3_addr_is_canonical 3 . -.Sh RETURN VALUES -.Fn IPAddressRange_new -returns a new -.Vt IPAddressRange -object with allocated, empty members, or -.Dv NULL -if an error occurs. -.Pp -.Fn IPAddressOrRange_new -returns a new, empty -.Vt IPAddressOrRange -object or -.Dv NULL -if an error occurs. -.Pp -.Fn IPAddressChoice_new -returns a new, empty -.Vt IPAddressChoice -object or -.Dv NULL -if an error occurs. -.Pp -.Fn IPAddressFamily_new -returns a new -.Vt IPAddressFamily -object with allocated, empty members, or -.Dv NULL -if an error occurs. -.Pp -The decoding functions -.Fn d2i_IPAddressRange , -.Fn d2i_IPAddressOrRange , -.Fn d2i_IPAddressChoice , -and -.Fn d2i_IPAddressFamily -return an -.Vt IPAddressRange , -an -.Vt IPAddressOrRange , -an -.Vt IPAddressChoice , -or an -.Vt IPAddressFamily -object, respectively, -or -.Dv NULL -if an error occurs. -.Pp -The encoding functions -.Fn i2d_IPAddressRange , -.Fn i2d_IPAddressOrRange , -.Fn i2d_IPAddressChoice , -and -.Fn i2d_IPAddressFamily -return the number of bytes successfully encoded -or a value <= 0 if an error occurs. -.Sh SEE ALSO -.Xr ASIdentifiers_new 3 , -.Xr ASN1_BIT_STRING_new 3 , -.Xr ASN1_OCTET_STRING_new 3 , -.Xr ASN1_OCTET_STRING_set 3 , -.Xr crypto 3 , -.Xr X509_new 3 , -.Xr X509v3_addr_add_inherit 3 , -.Xr X509v3_addr_inherits 3 , -.Xr X509v3_addr_subset 3 -.Sh STANDARDS -RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: -.Bl -dash -compact -.It -section 2.1.1: Encoding of an IP Address or Prefix -.It -section 2.1.2: Encoding of a Range of IP Addresses -.It -section 2.2.3: Syntax -.It -section 2.2.3.1: Type IPAddrBlocks -.It -section 2.2.3.2: Type IPAddressFamily -.It -section 2.2.3.3: Element addressFamily -.It -section 2.2.3.4: Element ipAddressChoice and Type IPAddressChoice -.It -section 2.2.3.5: Element inherit -.It -section 2.2.3.6: Element addressesOrRanges -.It -section 2.2.3.7: Type IPAddressOrRange -.It -section 2.2.3.8: Element addressPrefix and Type IPAddress -.It -section 2.2.3.9: Element addressRange and Type IPAddressRange -.El -.Pp -ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: -Information technology - ASN.1 encoding rules: -Specification of Basic Encoding Rules (BER), Canonical Encoding -Rules (CER) and Distinguished Encoding Rules (DER), -section 8.6: Encoding of a bitstring value -.Sh HISTORY -These functions first appeared in OpenSSL 0.9.8e -and have been available since -.Ox 7.1 . -.Sh BUGS -.\" The internals do not seem to consistently apply and check -.\" .Dv ASN1_STRING_FLAG_BITS_LEFT -.\" which may lead to incorrect encoding and misinterpretation -As it stands, the API is barely usable -due to missing convenience accessors, constructors and destructors -and due to the complete absence of API that checks that the -individual building blocks are correct. -Extracting information from a given object can be done relatively -safely. -However, constructing objects is very error prone, be it -by hand or using the bug-ridden -.Xr X509v3_addr_add_inherit 3 -API. -.Pp -RFC 3779 has element -.Dq addressesOrRanges . -Its type in this API is -.Vt IPAddressOrRanges . -- cgit v1.2.3-55-g6feb