Document X509v3_{addr,asid}_inherits(3)

Also note another bug in X509v3_asid_{canonize,is_canonical}(3).

6 files changed, 140 insertions, 5 deletions

diff --git a/lib/libcrypto/man/ASIdentifiers_new.3 b/lib/libcrypto/man/ASIdentifiers_new.3
index a67c54434c8..613fd3ce801 100644
--- a/lib/libcrypto/man/ASIdentifiers_new.3
+++ b/lib/libcrypto/man/ASIdentifiers_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASIdentifiers_new.3,v 1.5 2023/09/26 15:34:23 tb Exp $
+.\" $OpenBSD: ASIdentifiers_new.3,v 1.6 2023/09/26 20:42:45 tb Exp $
 .\"
 .\" Copyright (c) 2021 Theo Buehler <tb@openbsd.org>
 .\"
@@ -113,6 +113,7 @@ or a value <= 0 if an error occurs.
 .Xr IPAddressRange_new 3 ,
 .Xr X509_new 3 ,
 .Xr X509v3_asid_add_id_or_range 3
+.Xr X509v3_asid_inherits 3
 .Sh STANDARDS
 RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
 .Bl -dash -compact
diff --git a/lib/libcrypto/man/IPAddressRange_new.3 b/lib/libcrypto/man/IPAddressRange_new.3
index 262cbd8c81d..bee18bc0b49 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.2 2023/09/26 18:35:34 tb Exp $
+.\" $OpenBSD: IPAddressRange_new.3,v 1.3 2023/09/26 20:42:45 tb Exp $
 .\"
 .\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -464,6 +464,7 @@ or a value <= 0 if an error occurs.
 .Xr crypto 3 ,
 .Xr X509_new 3 ,
 .Xr X509v3_addr_add_inherit 3 ,
+.Xr X509v3_addr_inherits 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 9ab2a348232..9bf40343e4a 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.273 2023/09/26 18:35:34 tb Exp $
+# $OpenBSD: Makefile,v 1.274 2023/09/26 20:42:45 tb Exp $
 
 .include <bsd.own.mk>
 
@@ -394,6 +394,7 @@ MAN=	\
 	X509at_get_attr.3 \
 	X509v3_addr_add_inherit.3 \
 	X509v3_addr_get_range.3 \
+	X509v3_addr_inherits.3 \
 	X509v3_asid_add_id_or_range.3 \
 	X509v3_asid_add_id_or_range.3 \
 	X509v3_get_ext_by_NID.3 \
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index ebffc7e69ba..dea1b256ce6 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.40 2023/09/26 15:34:23 tb Exp $
+.\" $OpenBSD: X509_new.3,v 1.41 2023/09/26 20:42:45 tb Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -243,6 +243,8 @@ if an error occurs.
 .Xr X509_STORE_new 3 ,
 .Xr X509_TRUST_set 3 ,
 .Xr X509v3_addr_add_inherit 3 ,
+.Xr X509v3_addr_get_range 3 ,
+.Xr X509v3_addr_inherits 3 ,
 .Xr X509v3_asid_add_id_or_range 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
diff --git a/lib/libcrypto/man/X509v3_addr_inherits.3 b/lib/libcrypto/man/X509v3_addr_inherits.3
new file mode 100644
index 00000000000..a8465afb387
--- /dev/null
+++ b/lib/libcrypto/man/X509v3_addr_inherits.3
@@ -0,0 +1,106 @@
+.\" $OpenBSD: X509v3_addr_inherits.3,v 1.1 2023/09/26 20:42:45 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_INHERITS 3
+.Os
+.Sh NAME
+.Nm X509v3_addr_inherits ,
+.Nm X509v3_asid_inherits
+.Nd inheritance for the IP address and AS number delegation extensions
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft int
+.Fn X509v3_addr_inherits "IPAddrBlocks *addrblocks"
+.Ft int
+.Fn X509v3_asid_inherits "ASIdentifiers *asids"
+.Sh DESCRIPTION
+.Fn X509v3_addr_inherits
+determines if there is at least one address family in
+.Fa addrblocks
+that uses inheritance.
+.Pp
+.Fn X509v3_asid_inherits
+is intended to determine if at least one of
+the list of autonomous system numbers or
+the list of routing domain identifiers
+uses inheritance.
+.Sh RETURN VALUES
+.Fn X509v3_addr_inherits
+returns 1 if and only if
+.Fa addrblocks
+contains at least one
+.Fa IPAddressFamily
+object that is correctly marked
+.Dq inherit :
+its
+.Fa IPAddressChoice
+is of
+.Fa type
+.Dv IPAddressChoice_inherit
+and its
+.Fa inherit
+element is present.
+Otherwise it returns 0.
+.Pp
+.Fn X509v3_asid_inherits
+returns 1 if and only if
+at least one of the
+.Fa asnum
+or the
+.Fa rdi
+lists has
+.Fa type
+.Dv ASIdentifierChoice_inherit .
+Otherwise
+.Fn X509v3_asid_inherits 3
+returns 0.
+.Sh SEE ALSO
+.Xr ASIdentifiers_new 3 ,
+.Xr ASRange_new 3 ,
+.Xr crypto 3 ,
+.Xr IPAddressRange_new 3 ,
+.Xr X509_new 3 ,
+.Xr X509v3_addr_add_inherit 3 ,
+.Xr X509v3_asid_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.5: Element inherit
+.It
+section 3: AS identifiers delegation extension
+.It
+section 3.2.3.3: Element inherit
+.El
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.8e
+and have been available since
+.Ox 7.1 .
+.Sh BUGS
+.Fn X509v3_asid_inherits
+ignores whether the
+.Fa inherit
+is present or absent in the list that is considered to use inheritance.
+.Pp
+There is no API that determines whether all lists contained in an
+.Vt ASIdentifiers
+or an
+.Vt IPAddrBlocks
+objects inherit.
+See RFC 9287, 5.1.2 for an example where this is relevant.
diff --git a/lib/libcrypto/man/X509v3_asid_add_id_or_range.3 b/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
index 272acc31e2f..6d554e6a201 100644
--- a/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
+++ b/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.3 2023/09/26 08:56:18 tb Exp $
+.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.4 2023/09/26 20:42:45 tb Exp $
 .\"
 .\" Copyright (c) 2021-2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -297,3 +297,27 @@ does not prefer either representation over the other.
 The encodings of the two representations produced by
 .Xr i2d_ASIdentifiers 3
 are distinct.
+.Pp
+.Fn X509v3_asid_is_canonical
+does not fully check inheriting lists to be well formed.
+It only checks the
+.Fa type
+to be
+.Dv ASIdentifierChoice_inherit
+and ignores the presence or absence of the
+.Fa inherit
+element.
+.Fn X509v3_asid_canonize
+does not fix that up.
+This can lead to incorrect or unexpected DER encoding of
+.Dq canonical
+.Vt ASIdentifiers
+objects.
+In particular, it is possible to construct an
+.Vt ASIdentifiers
+object for which both
+.Fn X509v3_asid_is_canonical
+and
+.Xr X509v3_asid_inherits 3
+return 1, and after a round trip through DER the latter
+returns 0.