From: tb Date: Tue, 26 Sep 2023 20:42:45 +0000 (+0000) Subject: Document X509v3_{addr,asid}_inherits(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=7409c909a10cf581eafdf1b19bc29a3a58cb817d;p=openbsd Document X509v3_{addr,asid}_inherits(3) Also note another bug in X509v3_asid_{canonize,is_canonical}(3). --- 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 .\" @@ -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 .\" @@ -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 @@ -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 +.\" +.\" 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 .\" @@ -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.