From 1f84f19b21ef0072d204bbb8685b3ce0953393bf Mon Sep 17 00:00:00 2001 From: tb Date: Fri, 29 Sep 2023 08:57:49 +0000 Subject: [PATCH] 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. --- lib/libcrypto/man/ASIdentifiers_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_new.3 | 5 +- lib/libcrypto/man/X509v3_addr_add_inherit.3 | 5 +- lib/libcrypto/man/X509v3_addr_validate_path.3 | 202 ++++++++++++++++++ .../man/X509v3_asid_add_id_or_range.3 | 7 +- 6 files changed, 217 insertions(+), 10 deletions(-) create mode 100644 lib/libcrypto/man/X509v3_addr_validate_path.3 diff --git a/lib/libcrypto/man/ASIdentifiers_new.3 b/lib/libcrypto/man/ASIdentifiers_new.3 index ae5795c9a3a..c67a7c3f174 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.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 .\" @@ -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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index e6a97f30048..f42e9327ae2 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3 index a669bf06083..3e7fb0a79f8 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.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/lib/libcrypto/man/X509v3_addr_add_inherit.3 b/lib/libcrypto/man/X509v3_addr_add_inherit.3 index 81e73f76e54..bdfb5c757d2 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.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 .\" @@ -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/lib/libcrypto/man/X509v3_addr_validate_path.3 b/lib/libcrypto/man/X509v3_addr_validate_path.3 new file mode 100644 index 00000000000..1315e2013e9 --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/X509v3_asid_add_id_or_range.3 b/lib/libcrypto/man/X509v3_asid_add_id_or_range.3 index 1b42a449e15..f6b1c0347f0 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.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 .\" @@ -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 -- 2.20.1