From ce497e144fa224d1ac98b2bbb5aa439ba5a8178c Mon Sep 17 00:00:00 2001 From: tb Date: Thu, 28 Sep 2023 12:36:36 +0000 Subject: [PATCH] Document X509v3_{addr,asid}_subset.3 take two (missed cvs add) First RFC 3779 page without a BUG section. It could have one, but I'm in a lenient mood right now. Maybe it's just that this is bad but not quite as bad as EVP. --- lib/libcrypto/man/X509v3_addr_subset.3 | 176 +++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 lib/libcrypto/man/X509v3_addr_subset.3 diff --git a/lib/libcrypto/man/X509v3_addr_subset.3 b/lib/libcrypto/man/X509v3_addr_subset.3 new file mode 100644 index 00000000000..8107eb8884b --- /dev/null +++ b/lib/libcrypto/man/X509v3_addr_subset.3 @@ -0,0 +1,176 @@ +.\" $OpenBSD: X509v3_addr_subset.3,v 1.1 2023/09/28 12:36:36 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 28 2023 $ +.Dt X509V3_ADDR_SUBSET 3 +.Os +.Sh NAME +.Nm X509v3_addr_subset , +.Nm X509v3_asid_subset +.Nd RFC 3779 subset relationship +.Sh SYNOPSIS +.In openssl/x509v3.h +.Ft int +.Fn X509v3_addr_subset "IPAddrBlocks *child" "IPAddrBlocks *parent" +.Ft int +.Fn X509v3_asid_subset "ASIdentifiers *child" "ASIdentifiers *parent" +.Sh DESCRIPTION +.Fn X509v3_addr_subset +determines if all IP address resources present in +.Fa child +are contained in the corresponding resources in +.Fa parent . +.Pp +The implementation assumes but does not ensure that both +.Fa child +and +.Fa parent +are in canonical form as described in +.Xr X509v3_addr_is_canonical 3 . +In particular, both +.Fa child +and +.Fa parent +are sorted appropriately and they contain at most one +.Vt IPAddressFamily +object per address family identifier (AFI) and optional +subsequent address family identifier (SAFI). +.Pp +The checks are, in order: +.Bl -enum +.It +If +.Fa child +is +.Dv NULL +or identical to +.Fa parent +then +.Fa child +is a subset of +.Fa parent . +(In particular, a +.Dv NULL +.Fa parent +is allowed for a +.Dv NULL +.Fa child Ns .) +.It +If +.Fa parent +is +.Dv NULL +then +.Fa child +is not a subset of +.Fa parent . +.It +If +.Xr X509v3_addr_inherits 3 +determines that +.Fa child +inherits or that +.Fa parent +inherits +then +.Fa child +is not a subset of +.Fa parent . +.It +Each address prefix or range in +.Fa child +must be a subset of an address prefix or range in the +.Fa parent , +taking AFI and optional SAFI into account: +.Bl -bullet -compact +.It +For each +.Vt IPAddressFamily +of +.Fa child +there must be an +.Vt IPAddressFamily +of +.Fa parent +with the same AFI and optional SAFI. +.It +Since the address prefixes and ranges in corresponding +.Vt IPAddressFamily +objects in +.Fa child +and +.Fa parent +are sorted in ascending order, +and do not overlap, +they can be traversed simultaneously in linear time. +For each prefix or range in +.Fa child +there must be a prefix or range in +.Fa parent +whose minimal address is smaller +and whose maximal address is larger. +.El +If any of these steps fails, +.Fa child +is not a subset of +.Fa parent . +.El +.Pp +.Fn X509v3_asid_subset +determines if all AS identifier resources in +.Fa child +are contained in the corresponding resources in +.Fa parent . +.Pp +The description for +.Fn X509v3_addr_subset +applies mutatis mutandis. +In particular, +.Fa child +and +.Fa parent +must be in canonical form per +.Xr X509v3_asid_is_canonical 3 , +but this is not enforced. +.Sh RETURN VALUES +.Fn X509v3_addr_subset +and +.Fn X509v3_asid_subset +return 1 if and only if +.Fa child +is a subset of +.Fa parent , +otherwise they return 0. +If both +.Fa child +and +.Fa parent +are in canonical form, +they cannot fail. +.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. +.Sh HISTORY +These functions first appeared in OpenSSL 0.9.8e +and have been available since +.Ox 7.1 . -- 2.20.1