-.\" $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>
.\"
.\" 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
.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 *
.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:
-.\" $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>
.\"
.\" 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
.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 *"
.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
.Fn ASRange_new
returns a new
.Vt ASRange
-object or
+object with allocated, empty members, or
.Dv NULL
if an error occurs.
.Pp
-.\" $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>
.\"
.\" 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
.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 *"
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
.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
.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
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.
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 .
-.\" $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>
.\"
.\" 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
.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
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.
.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
.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 ,
.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
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
.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.
-.\" $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>
.\"
.\" 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
.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
-.\" $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>
.\"
.\" 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
.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
.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:
.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
projects / openbsd / commitdiff