From 9d9dd090f076aca2efcaf66f403b429e9af655c9 Mon Sep 17 00:00:00 2001 From: tb Date: Tue, 26 Sep 2023 18:35:34 +0000 Subject: [PATCH] Document X509v3_addr_get_{afi,range}(3) --- lib/libcrypto/man/IPAddressRange_new.3 | 4 +- lib/libcrypto/man/Makefile | 4 +- lib/libcrypto/man/X509v3_addr_add_inherit.3 | 5 +- lib/libcrypto/man/X509v3_addr_get_range.3 | 134 ++++++++++++++++++++ 4 files changed, 142 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/X509v3_addr_get_range.3 diff --git a/lib/libcrypto/man/IPAddressRange_new.3 b/lib/libcrypto/man/IPAddressRange_new.3 index 7a71ac7ffa8..262cbd8c81d 100644 --- a/lib/libcrypto/man/IPAddressRange_new.3 +++ b/lib/libcrypto/man/IPAddressRange_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: IPAddressRange_new.3,v 1.1 2023/09/26 15:34:23 tb Exp $ +.\" $OpenBSD: IPAddressRange_new.3,v 1.2 2023/09/26 18:35:34 tb Exp $ .\" .\" Copyright (c) 2023 Theo Buehler .\" @@ -463,7 +463,7 @@ or a value <= 0 if an error occurs. .Xr ASN1_OCTET_STRING_set 3 , .Xr crypto 3 , .Xr X509_new 3 , -.Xr X509v3_addr_add_inherit 3 +.Xr X509v3_addr_add_inherit 3 , .Sh STANDARDS RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: .Bl -dash -compact diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 0f501ceb833..9ab2a348232 100644 --- a/lib/libcrypto/man/Makefile +++ b/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.272 2023/09/26 15:34:23 tb Exp $ +# $OpenBSD: Makefile,v 1.273 2023/09/26 18:35:34 tb Exp $ .include @@ -393,6 +393,8 @@ MAN= \ X509at_add1_attr.3 \ X509at_get_attr.3 \ X509v3_addr_add_inherit.3 \ + X509v3_addr_get_range.3 \ + X509v3_asid_add_id_or_range.3 \ X509v3_asid_add_id_or_range.3 \ X509v3_get_ext_by_NID.3 \ a2d_ASN1_OBJECT.3 \ diff --git a/lib/libcrypto/man/X509v3_addr_add_inherit.3 b/lib/libcrypto/man/X509v3_addr_add_inherit.3 index 8d304751817..887a5ecb214 100644 --- a/lib/libcrypto/man/X509v3_addr_add_inherit.3 +++ b/lib/libcrypto/man/X509v3_addr_add_inherit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509v3_addr_add_inherit.3,v 1.3 2023/09/26 15:34:23 tb Exp $ +.\" $OpenBSD: X509v3_addr_add_inherit.3,v 1.4 2023/09/26 18:35:34 tb Exp $ .\" .\" Copyright (c) 2023 Theo Buehler .\" @@ -396,7 +396,8 @@ is desired. .Xr inet_ntop 3 , .Xr IPAddressRange_new 3 , .Xr X509_new 3 , -.Xr X509v3_asid_add_id_or_range 3 +.Xr X509v3_asid_add_id_or_range 3 , +.Xr X509v3_asid_get_range 3 .Sh STANDARDS RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: .Bl -dash -compact diff --git a/lib/libcrypto/man/X509v3_addr_get_range.3 b/lib/libcrypto/man/X509v3_addr_get_range.3 new file mode 100644 index 00000000000..a84b7cd5f2c --- /dev/null +++ b/lib/libcrypto/man/X509v3_addr_get_range.3 @@ -0,0 +1,134 @@ +.\" $OpenBSD: X509v3_addr_get_range.3,v 1.1 2023/09/26 18:35:34 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: September 26 2023 $ +.Dt X509V3_ADDR_GET_RANGE 3 +.Os +.Sh NAME +.Nm X509v3_addr_get_afi , +.Nm X509v3_addr_get_range +.Nd parse helpers for the IP address delegation extension +.Sh SYNOPSIS +.In openssl/x509v3.h +.Ft unsigned +.Fn X509v3_addr_get_afi "const IPAddressFamily *af" +.Ft int +.Fo X509v3_addr_get_range +.Fa "IPAddressOrRange *aor" +.Fa "const unsigned afi" +.Fa "unsigned char *min" +.Fa "unsigned char *max" +.Fa "const int length" +.Fc +.Sh DESCRIPTION +.Fn X509v3_addr_get_afi +returns the address family identifier (AFI) of +.Fa af . +.Pp +.Fn X509v3_addr_get_range +converts the minimum and maximum addresses in +the address prefix or range +.Fa aor +from internal encoding to IP addresses in network byte order +and places copies in the arrays +.Fa min +and +.Fa max , +of size +.Fa length . +The +.Fa length +must be large enough to accommodate an address for +.Fa afi , +which for +.Dv IANA_AFI_IPV4 , +is at least 4, +and for +.Dv IANA_AFI_IPV6 +at least 16. +.Sh RETURN VALUES +.Fn X509v3_addr_get_afi +returns the afi encoded in +.Fa af +or 0 if +.Fa af +does not contain a valid AFI, or if the AFI is not IPv4 or IPv6. +.Pp +.Fn X509v3_addr_get_range +returns the number of bytes copied into +.Fa min +and +.Fa max +or 0 on error. +An error occurs if +.Fa aor +is malformed, if +.Fa afi +is not +.Dv IANA_AFI_IPV4 +or +.Dv IANA_AFI_IPV6 , +if either +.Fa min +or +.Fa max +is +.Dv NULL , +or if +.Fa length +is smaller than 4 or 16, respectively. +.Sh SEE ALSO +.Xr crypto 3 , +.Xr inet_ntop 3 , +.Xr IPAddressRange_new 3 , +.Xr X509_new 3 , +.Xr X509v3_addr_add_inherit 3 +.Sh STANDARDS +RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers: +.Bl -dash -compact +.It +section 2: IP Address delegation extension +.It +section 2.2.3.3: Element addressFamily +.It +section 2.2.3.7: Type IPAddressOrRange +.It +section 2.2.3.8: Element addressPrefix and Type IPAddress +.El +.Pp +.Rs +.%T Address Family Numbers +.%U https://www.iana.org/assignments/address-family-numbers +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . +.Sh BUGS +There is no accessor for the SAFI of +.Fa af . +.Pp +An error from +.Fn X509v3_addr_get_afi +is indistinguishable from the reserved AFI 0 being set on +.Fa af . +.Pp +It is not entirely clear how a caller is supposed to obtain an +.Vt IPAddressFamily +object or an +.Vt IPAddressOrRange +object without reaching into various structs documented in +.Xr IPAddressRange_new 3 . -- 2.20.1