Document X509v3_addr_get_{afi,range}(3)

4 files changed, 142 insertions, 5 deletions

diff --git a/src/lib/libcrypto/man/IPAddressRange_new.3 b/src/lib/libcrypto/man/IPAddressRange_new.3
index 7a71ac7ffa..262cbd8c81 100644
--- a/src/lib/libcrypto/man/IPAddressRange_new.3
+++ b/src/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 <tb@openbsd.org>
 .\"
@@ -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/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 0f501ceb83..9ab2a34823 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/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 <bsd.own.mk>
 
@@ -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/src/lib/libcrypto/man/X509v3_addr_add_inherit.3 b/src/lib/libcrypto/man/X509v3_addr_add_inherit.3
index 8d30475181..887a5ecb21 100644
--- a/src/lib/libcrypto/man/X509v3_addr_add_inherit.3
+++ b/src/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 <tb@openbsd.org>
 .\"
@@ -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/src/lib/libcrypto/man/X509v3_addr_get_range.3 b/src/lib/libcrypto/man/X509v3_addr_get_range.3
new file mode 100644
index 0000000000..a84b7cd5f2
--- /dev/null
+++ b/src/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 <tb@openbsd.org>
+.\"
+.\" 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 .