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.

1 files changed, 202 insertions, 0 deletions

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 .