From 3806ee51ef65c1df77d3387154f4bee59943c24c Mon Sep 17 00:00:00 2001
From: tb <tb@openbsd.org>
Date: Wed, 27 Sep 2023 08:46:46 +0000
Subject: [PATCH] Various small tweaks in the RFC 3779 docs

Mention a few more bugs and unify manpage descriptions
---
 lib/libcrypto/man/ASIdentifiers_new.3         |  8 ++--
 lib/libcrypto/man/ASRange_new.3               | 18 ++++----
 lib/libcrypto/man/IPAddressRange_new.3        | 35 ++++++++--------
 lib/libcrypto/man/X509v3_addr_add_inherit.3   | 42 ++++++++++++-------
 lib/libcrypto/man/X509v3_addr_inherits.3      |  8 ++--
 .../man/X509v3_asid_add_id_or_range.3         | 16 ++++---
 6 files changed, 69 insertions(+), 58 deletions(-)

diff --git a/lib/libcrypto/man/ASIdentifiers_new.3 b/lib/libcrypto/man/ASIdentifiers_new.3
index 613fd3ce801..4f6bf67f10f 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.6 2023/09/26 20:42:45 tb Exp $
+.\" $OpenBSD: ASIdentifiers_new.3,v 1.7 2023/09/27 08:46:46 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 26 2023 $
+.Dd $Mdocdate: September 27 2023 $
 .Dt ASIDENTIFIERS_NEW 3
 .Os
 .Sh NAME
@@ -22,7 +22,7 @@
 .Nm ASIdentifiers_free ,
 .Nm d2i_ASIdentifiers ,
 .Nm i2d_ASIdentifiers
-.Nd X509v3 certificate extension for autonomous system identifier delegation
+.Nd RFC 3779 autonomous system identifier delegation extensions
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft ASIdentifiers *
@@ -112,7 +112,7 @@ or a value <= 0 if an error occurs.
 .Xr crypto 3 ,
 .Xr IPAddressRange_new 3 ,
 .Xr X509_new 3 ,
-.Xr X509v3_asid_add_id_or_range 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:
diff --git a/lib/libcrypto/man/ASRange_new.3 b/lib/libcrypto/man/ASRange_new.3
index 75b911c5888..12eff267929 100644
--- a/lib/libcrypto/man/ASRange_new.3
+++ b/lib/libcrypto/man/ASRange_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASRange_new.3,v 1.4 2023/09/26 15:34:23 tb Exp $
+.\" $OpenBSD: ASRange_new.3,v 1.5 2023/09/27 08:46:46 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 26 2023 $
+.Dd $Mdocdate: September 27 2023 $
 .Dt ASRANGE_NEW 3
 .Os
 .Sh NAME
@@ -30,7 +30,7 @@
 .Nm ASIdentifierChoice_free ,
 .Nm d2i_ASIdentifierChoice ,
 .Nm i2d_ASIdentifierChoice
-.Nd Autonomous system identifiers and ranges
+.Nd RFC 3779 autonomous system identifiers and ranges
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft "ASRange *"
@@ -87,21 +87,21 @@ are building blocks of the
 .Vt ASIdentifiers
 type representing the RFC 3779
 autonomous system identifier delegation extension.
-See
-.Xr ASIdentifiers_new 3
-and
-.Xr X509v3_asid_add_id_or_range 3
-for more details.
 .Pp
 All
 .Vt ASN1_INTEGER Ns s
 in this manual should be representable as unsigned 32-bit integers.
+The API performs no corresponding checks.
 The library provides no convenient way of setting the value of an
 .Vt ASN1_INTEGER
 directly.
 A detour via a
 .Vt BIGNUM
 or a string is unavoidable.
+To retrieve the value of an
+.Vt ASN1_INTEGER ,
+use
+.Xr ASN1_INTEGER_get_uint64 3 .
 .Pp
 The
 .Vt ASRange
@@ -310,7 +310,7 @@ object of
 .Fn ASRange_new
 returns a new
 .Vt ASRange
-object or
+object with allocated, empty members, or
 .Dv NULL
 if an error occurs.
 .Pp
diff --git a/lib/libcrypto/man/IPAddressRange_new.3 b/lib/libcrypto/man/IPAddressRange_new.3
index bee18bc0b49..07c57f3e5d7 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.3 2023/09/26 20:42:45 tb Exp $
+.\" $OpenBSD: IPAddressRange_new.3,v 1.4 2023/09/27 08:46:46 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 26 2023 $
+.Dd $Mdocdate: September 27 2023 $
 .Dt IPADDRESSRANGE_NEW 3
 .Os
 .Sh NAME
@@ -34,7 +34,7 @@
 .Nm IPAddressFamily_free ,
 .Nm d2i_IPAddressFamily ,
 .Nm i2d_IPAddressFamily
-.Nd IP address prefixes and ranges
+.Nd RFC 3779 IP address prefixes and ranges
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft "IPAddressRange *"
@@ -106,25 +106,21 @@ and
 are building blocks of the RFC 3779
 .Vt IPAddrBlocks
 type representing the IP address delegation extension.
-See
-.Xr X509v3_addr_add_inherit 3
-for more details.
 .Pp
 Per RFC 3779, section 2.1.1,
 an IPv4 or an IPv6 address is encoded in network byte order in an
 ASN.1 BIT STRING of bit size 32 or 128 bits, respectively.
-The bit size of a prefix is its prefix length,
-in other words, all insignificant zero bits are omitted.
+The bit size of a prefix is its prefix length.
+In other words, all insignificant zero bits are omitted
+from the encoding.
 An address range is expressed as a pair of BIT STRINGs
 where all least significant zero bits of the lower bound
 and the all least significant one bits of the upper bound are omitted.
-Whether a prefix or a range represents a range of IPv4 address or
-an IPv6 address must be derived from the context.
 .Pp
 The library provides no API for directly converting an IP address or
 prefix (in any form) to and from an
-.Vt ASN1_BIT_STRING
-and it also provides no API for directly handling ranges.
+.Vt ASN1_BIT_STRING .
+It also provides no API for directly handling ranges.
 The
 .Vt ASN1_BIT_STRING
 internals are subtle and directly manipulating them in the
@@ -175,7 +171,7 @@ is
 .Dv NULL ,
 no action occurs.
 .Pp
-There is no dedicated type to represent the
+There is no dedicated type representing the
 .Vt IPAddress
 type defined in RFC 3779 section 2.2.3.8.
 The API uses
@@ -404,11 +400,11 @@ structure, see
 .Fn IPAddressRange_new
 returns a new
 .Vt IPAddressRange
-object or
+object with allocated, empty members, or
 .Dv NULL
 if an error occurs.
 .Pp
-.Fn IPAddressRange_new
+.Fn IPAddressOrRange_new
 returns a new, empty
 .Vt IPAddressOrRange
 object or
@@ -423,8 +419,8 @@ object or
 if an error occurs.
 .Pp
 .Fn IPAddressFamily_new
-returns a new,
-.Vt IPAddressChoice
+returns a new
+.Vt IPAddressFamily
 object with allocated, empty members, or
 .Dv NULL
 if an error occurs.
@@ -513,3 +509,8 @@ However, constructing objects is very error prone, be it
 by hand or using the bug-ridden
 .Xr X509v3_addr_add_inherit 3
 API.
+.Pp
+RFC 3779 has element
+.Dq addressesOrRanges .
+Its type in this API is
+.Vt IPAddressOrRanges .
diff --git a/lib/libcrypto/man/X509v3_addr_add_inherit.3 b/lib/libcrypto/man/X509v3_addr_add_inherit.3
index 887a5ecb214..3ca9bc59aeb 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.4 2023/09/26 18:35:34 tb Exp $
+.\" $OpenBSD: X509v3_addr_add_inherit.3,v 1.5 2023/09/27 08:46:46 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 26 2023 $
+.Dd $Mdocdate: September 27 2023 $
 .Dt X509V3_ADDR_ADD_INHERIT 3
 .Os
 .Sh NAME
@@ -23,8 +23,7 @@
 .Nm X509v3_addr_add_range ,
 .Nm X509v3_addr_canonize ,
 .Nm X509v3_addr_is_canonical
-.Nd construct X509v3 IP address blocks extensions and
-bring them into canonical form
+.Nd RFC 3779 IP address delegation extensions
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft int
@@ -63,15 +62,18 @@ An
 object represents the content of
 an X509v3 IP address blocks delegation extension
 as defined in RFC 3779, section 2.2.3.1.
-It can hold lists of delegated IP address prefixes and
-IP address ranges.
+It holds lists of IP address prefixes and IP address ranges
+delegated from the issuer to the subject of the certificate.
 It can be instantiated as explained in the EXAMPLES section
 and its internals are documented in
 .Xr IPAddressRange_new 3 .
-Each list is uniquely identified by
+.Pp
+Each list in a well-formed
+.Vt IPAddrBlocks
+object is uniquely identified by
 an address family identifier (AFI) and
 an optional subsequent address family identifier (SAFI).
-Each list can be absent or it can contain a single
+Lists can be absent or can contain an
 .Dq inherit
 marker to indicate that the resources are to be inherited
 from the corresponding list of the issuer certificate.
@@ -171,7 +173,7 @@ In case the range of IP addresses between
 .Fa min
 and
 .Fa max
-is a prefix, a prefix will be added.
+is a prefix, a prefix will be added instead of a range.
 It is the caller's responsibility to ensure that
 .Fa min
 is less than or equal to
@@ -190,7 +192,8 @@ An
 .Vt IPAddrBlocks
 object is said to be in canonical form if it conforms
 to the ordering specified in RFC 3779:
-section 2.2.3.3 requires that the lists be sorted first by increasing
+section 2.2.3.3 requires that
+the list of lists be sorted first by increasing
 .Fa afi
 and then by increasing
 .Fa safi ,
@@ -397,7 +400,7 @@ is desired.
 .Xr IPAddressRange_new 3 ,
 .Xr X509_new 3 ,
 .Xr X509v3_asid_add_id_or_range 3 ,
-.Xr X509v3_asid_get_range 3
+.Xr X509v3_addr_get_range 3
 .Sh STANDARDS
 RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
 .Bl -dash -compact
@@ -434,12 +437,12 @@ is not public.
 The above examples show how to implement the four missing functions
 with public API.
 .Pp
-.Fn X509v3_asid_add_range
+.Fn X509v3_addr_add_range
 should check for inverted range bounds and overlaps
 on insertion and fail instead of creating a nonsensical
-.Fa asid
+.Fa addr
 that fails to be canonized by
-.Fn X509v3_asid_canonize .
+.Fn X509v3_addr_canonize .
 .Pp
 If
 .Dv NULL
@@ -457,4 +460,13 @@ crashes with a
 .Dv NULL
 dereference.
 .Pp
-The only supported AFIs are IPv4 and IPv6, but this is not enforced.
+The code only supports the IPv4 and IPv6 AFIs.
+This is not consistently enforced across implementations.
+.Pp
+.Fn X509v3_addr_add_range
+fails to clear the unused bits set to 1 in the last octet of
+the
+.Vt ASN1_BIT_STRING
+representation of
+.Fa max .
+This confuses some software.
diff --git a/lib/libcrypto/man/X509v3_addr_inherits.3 b/lib/libcrypto/man/X509v3_addr_inherits.3
index a8465afb387..0c3c35d4a3f 100644
--- a/lib/libcrypto/man/X509v3_addr_inherits.3
+++ b/lib/libcrypto/man/X509v3_addr_inherits.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509v3_addr_inherits.3,v 1.1 2023/09/26 20:42:45 tb Exp $
+.\" $OpenBSD: X509v3_addr_inherits.3,v 1.2 2023/09/27 08:46:46 tb Exp $
 .\"
 .\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
 .\"
@@ -14,13 +14,13 @@
 .\" 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 $
+.Dd $Mdocdate: September 27 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
+.Nd RFC 3779 inheritance
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft int
@@ -96,7 +96,7 @@ and have been available since
 .Fn X509v3_asid_inherits
 ignores whether the
 .Fa inherit
-is present or absent in the list that is considered to use inheritance.
+element 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
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 6d554e6a201..c9ff6bf13b1 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.4 2023/09/26 20:42:45 tb Exp $
+.\" $OpenBSD: X509v3_asid_add_id_or_range.3,v 1.5 2023/09/27 08:46:46 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 26 2023 $
+.Dd $Mdocdate: September 27 2023 $
 .Dt X509V3_ASID_ADD_ID_OR_RANGE 3
 .Os
 .Sh NAME
@@ -22,8 +22,7 @@
 .Nm X509v3_asid_add_inherit ,
 .Nm X509v3_asid_canonize ,
 .Nm X509v3_asid_is_canonical
-.Nd construct and validate individual X509v3 certificate extensions for
-autonomous system identifier delegation
+.Nd RFC 3779 autonomous system identifier delegation extension
 .Sh SYNOPSIS
 .In openssl/x509v3.h
 .Ft int
@@ -57,7 +56,7 @@ and its internals are documented in
 .Xr ASRange_new 3 .
 .Pp
 An autonomous system is identified by an unsigned 32-bit integer,
-called an AS number.
+called an AS identifier or AS number.
 An
 .Vt ASIdentifiers
 object can hold two lists:
@@ -132,15 +131,14 @@ or
 .Dv V3_ASID_RDI )
 in
 .Fa asid
-and marks it
+if necessary and marks it
 .Dq inherit .
 This fails if
 .Fa asid
 already contains a list of
 .Fa type
-that isn't marked
-.Dq inherit ,
-otherwise no action occurs.
+that is not marked
+.Dq inherit .
 .Pp
 .Fn X509v3_asid_canonize
 attempts to bring both lists in
-- 
2.20.1