Document X509v3_{addr,asid}_validate_{path,resource_set}(3)

These were the last four RFC 3779 things that check_complete.pl x509v3
complained about. I will surely tweak and try to improve a few things
in the coming days, but the pages should now be stable enough that
review efforts will likely not be wasted. Any feedback appreciated.

6 files changed, 217 insertions, 10 deletions

diff --git a/src/lib/libcrypto/man/ASIdentifiers_new.3 b/src/lib/libcrypto/man/ASIdentifiers_new.3
index ae5795c9a3..c67a7c3f17 100644
--- a/src/lib/libcrypto/man/ASIdentifiers_new.3
+++ b/src/lib/libcrypto/man/ASIdentifiers_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASIdentifiers_new.3,v 1.8 2023/09/28 12:35:31 tb Exp $
+.\" $OpenBSD: ASIdentifiers_new.3,v 1.9 2023/09/29 08:57:49 tb Exp $
 .\"
 .\" Copyright (c) 2021 Theo Buehler <tb@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 28 2023 $
+.Dd $Mdocdate: September 29 2023 $
 .Dt ASIDENTIFIERS_NEW 3
 .Os
 .Sh NAME
@@ -116,6 +116,7 @@ or a value <= 0 if an error occurs.
 .Xr X509v3_addr_get_range 3 ,
 .Xr X509v3_addr_inherits 3 ,
 .Xr X509v3_addr_subset 3 ,
+.Xr X509v3_addr_validate_path 3 ,
 .Xr X509v3_asid_add_id_or_range 3
 .Sh STANDARDS
 RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index e6a97f3004..f42e9327ae 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.275 2023/09/28 12:35:31 tb Exp $
+# $OpenBSD: Makefile,v 1.276 2023/09/29 08:57:49 tb Exp $
 
 .include <bsd.own.mk>
 
@@ -396,6 +396,7 @@ MAN=	\
         X509v3_addr_get_range.3 \
         X509v3_addr_inherits.3 \
         X509v3_addr_subset.3 \
+        X509v3_addr_validate_path.3 \
         X509v3_asid_add_id_or_range.3 \
         X509v3_asid_add_id_or_range.3 \
         X509v3_get_ext_by_NID.3 \
diff --git a/src/lib/libcrypto/man/X509_new.3 b/src/lib/libcrypto/man/X509_new.3
index a669bf0608..3e7fb0a79f 100644
--- a/src/lib/libcrypto/man/X509_new.3
+++ b/src/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.42 2023/09/28 12:35:31 tb Exp $
+.\" $OpenBSD: X509_new.3,v 1.43 2023/09/29 08:57:49 tb Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 28 2023 $
+.Dd $Mdocdate: September 29 2023 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -246,6 +246,7 @@ if an error occurs.
 .Xr X509v3_addr_get_range 3 ,
 .Xr X509v3_addr_inherits 3 ,
 .Xr X509v3_addr_subset 3 ,
+.Xr X509v3_addr_validate_path 3 ,
 .Xr X509v3_asid_add_id_or_range 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
diff --git a/src/lib/libcrypto/man/X509v3_addr_add_inherit.3 b/src/lib/libcrypto/man/X509v3_addr_add_inherit.3
index 81e73f76e5..bdfb5c757d 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.6 2023/09/28 12:35:31 tb Exp $
+.\" $OpenBSD: X509v3_addr_add_inherit.3,v 1.7 2023/09/29 08:57:49 tb Exp $
 .\"
 .\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 28 2023 $
+.Dd $Mdocdate: September 29 2023 $
 .Dt X509V3_ADDR_ADD_INHERIT 3
 .Os
 .Sh NAME
@@ -400,6 +400,7 @@ is desired.
 .Xr IPAddressRange_new 3 ,
 .Xr X509_new 3 ,
 .Xr X509v3_addr_get_range 3 ,
+.Xr X509v3_addr_validate_path 3 ,
 .Xr X509v3_asid_add_id_or_range 3
 .Sh STANDARDS
 RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
diff --git a/src/lib/libcrypto/man/X509v3_addr_validate_path.3 b/src/lib/libcrypto/man/X509v3_addr_validate_path.3
new file mode 100644
index 0000000000..1315e2013e
--- /dev/null
+++ b/src/lib/libcrypto/man/X509v3_addr_validate_path.3
@@ -0,0 +1,202 @@
+.\" $OpenBSD: X509v3_addr_validate_path.3,v 1.1 2023/09/29 08:57:49 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 29 2023 $
+.Dt X509V3_ADDR_VALIDATE_PATH 3
+.Os
+.Sh NAME
+.Nm X509v3_addr_validate_path ,
+.Nm X509v3_addr_validate_resource_set ,
+.Nm X509v3_asid_validate_path ,
+.Nm X509v3_asid_validate_resource_set
+.Nd RFC 3779 path validation for IP address and AS number delegation
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft int
+.Fn X509v3_addr_validate_path "X509_STORE_CTX *ctx"
+.Ft int
+.Fo X509v3_addr_validate_resource_set
+.Fa "STACK_OF(X509) *chain"
+.Fa "IPAddrBlocks *addrblocks"
+.Fa "int allow_inheritance"
+.Fc
+.Ft int
+.Fn X509v3_asid_validate_path "X509_STORE_CTX *ctx"
+.Ft int
+.Fo X509v3_asid_validate_resource_set
+.Fa "STACK_OF(X509) *chain"
+.Fa "ASIdentifiers *asid"
+.Fa "int allow_inheritance"
+.Fc
+.Sh DESCRIPTION
+Both RFC 3779 extensions require additional checking in the certification
+path validation.
+.Bl -enum
+.It
+The initial set of allowed IP address and AS number resources is defined in
+the trust anchor; inheritance is not allowed in the trust anchor.
+.It
+All IP address delegation or AS number delegation extensions
+must be in canonical form according to
+.Xr X509v3_addr_is_canonical 3
+and
+.Xr X509v3_asid_is_canonical 3 .
+.It
+If the IP address delegation extension is present in a certificate,
+it must also be present in its issuer.
+Similarly for AS identifiers.
+.It
+An issuer may only delegate resources present in its
+RFC 3779 extensions.
+.El
+.Pp
+.Fn X509v3_addr_validate_path
+and
+.Fn X509v3_asid_validate_path
+are called from
+.Xr X509_verify_cert 3
+as part of the verification chain building.
+On encountering an error or a violation of the above rules,
+.Fa error ,
+.Fa error_depth ,
+and
+.Fa current_cert
+are set on
+.Fa ctx
+and the verify callback is called with
+.Fa ok
+set to 0.
+.Dv X509_V_ERR_INVALID_EXTENSION
+indicates a non-canonical resource,
+.Dv X509_V_ERR_UNNESTED_RESOURCE
+indicates a violation of the other rules above.
+In rare circumstances, the error can be
+.Dv X509_V_ERR_UNSPECIFIED
+and for IP address resources
+.Dv X509_V_ERR_OUT_OF_MEM
+is also possible.
+.Pp
+.Fn X509v3_addr_validate_resource_set
+validates the resources in
+.Fa addrblocks
+against a specific certificate
+.Fa chain .
+After checking that
+.Fa addrblocks
+is canonical, its IP addresses are checked to be covered in
+the certificate at depth 0,
+then the chain is walked all the way to the trust anchor
+until an error or a violation of the above rules is encountered.
+.Fa addrblocks
+is allowed to use inheritance according to
+.Xr X509v3_addr_inherits 3
+if and only if
+.Fa allow_inherit
+is non-zero.
+.Pp
+.Fn X509v3_asid_validate_resource_set
+performs similar checks as
+.Fn X509v3_addr_validate_resource_set
+for
+.Fa asid .
+.Sh RETURN VALUES
+All these functions return 1 on successful validation and 0 otherwise.
+.Pa
+For
+.Fn X509v3_addr_validate_path
+and
+.Fn X509v3_asid_validate_path
+a non-empty
+.Fa chain
+and a
+.Fa verify_cb
+must be present on
+.Fa ctx ,
+otherwise they fail and set the
+.Fa error
+on
+.Fa ctx
+to
+.Dv X509_V_ERR_UNSPECIFIED .
+The
+.Fa verify_cb
+is called with the error codes described above
+on most errors encountered during validation.
+Some malformed extensions can lead to an error
+that cannot be intercepted by the callback.
+With the exception of an allocation error,
+no error codes are set on the error stack.
+.Pp
+.Fn X509v3_addr_validate_resource_set
+and
+.Fn X509v3_asid_validate_resource_set
+accept a
+.Dv NULL
+.Fa addrblocks
+or
+.Fa asid
+as valid.
+They fail if
+.Fa chain
+is
+.Dv NULL
+or empty.
+If
+.Fa allow_inheritance
+is 0 ,
+.Fa addrblocks
+or
+.Fa asid
+is checked for inheritance with
+.Xr X509v3_addr_inherits 3
+or
+.Xr X509v3_asid_inherits 3 .
+The remaining failure cases are the same as for
+.Fn X509v3_addr_validate_path
+and
+.Fn X509v3_asid_validate_path .
+They cannot and do not attempt to communicate
+the cause of the error to the caller.
+.Sh SEE ALSO
+.Xr ASIdentifiers_new 3 ,
+.Xr crypto 3 ,
+.Xr IPAddressRange_new 3 ,
+.Xr X509_new 3 ,
+.Xr X509_STORE_CTX_get_error 3 ,
+.Xr X509_verify_cert 3 ,
+.Xr X509v3_addr_add_inherit 3 ,
+.Xr X509v3_addr_inherits 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 2.3: IP Address Delegation Extension Certification Path Validation
+.It
+section 3.3: Autonomous System Identifier Delegation Extension Certification
+Path Validation
+.El
+.Pp
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate
+and Certificate Revocation List (CRL) Profile
+.Bl -dash -compact
+.It
+section 6: Certification Path Validation
+.El
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.8e
+and have been available since
+.Ox 7.1 .
diff --git a/src/lib/libcrypto/man/X509v3_asid_add_id_or_range.3 b/src/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
index 1b42a449e1..f6b1c0347f 100644
--- a/src/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
+++ b/src/lib/libcrypto/man/X509v3_asid_add_id_or_range.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.6 2023/09/28 12:35:31 tb Exp $
+.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.7 2023/09/29 08:57:49 tb Exp $
 .\"
 .\" Copyright (c) 2021-2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 28 2023 $
+.Dd $Mdocdate: September 29 2023 $
 .Dt X509V3_ASID_ADD_ID_OR_RANGE 3
 .Os
 .Sh NAME
@@ -242,7 +242,8 @@ failure.
 .Xr crypto 3 ,
 .Xr s2i_ASN1_INTEGER 3 ,
 .Xr X509_new 3 ,
-.Xr X509v3_addr_add_inherit 3
+.Xr X509v3_addr_add_inherit 3 ,
+.Xr X509v3_addr_validate_path 3
 .Sh STANDARDS
 RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers,
 .Bl -dash -compact