New manual page documenting the usual four ASN.1 functions for both

ASRange and ASIdOrRange

4 files changed, 263 insertions, 3 deletions

diff --git a/lib/libcrypto/man/ASIdentifiers_new.3 b/lib/libcrypto/man/ASIdentifiers_new.3
index 262c760f170..f6ab5e5aaf7 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.2 2023/09/25 11:12:08 tb Exp $
+.\" $OpenBSD: ASIdentifiers_new.3,v 1.3 2023/09/25 11:59:10 tb Exp $
 .\"
 .\" Copyright (c) 2021 Theo Buehler <tb@openbsd.org>
 .\"
@@ -105,6 +105,7 @@ on if a decoding or memory allocation error occurs.
 returns the number of bytes successfully encoded
 or a value <= 0 if an error occurs.
 .Sh SEE ALSO
+.Xr ASRange_new 3 ,
 .Xr crypto 3 ,
 .Xr X509_new 3 ,
 .Xr X509v3_asid_add_id_or_range 3 ,
diff --git a/lib/libcrypto/man/ASRange_new.3 b/lib/libcrypto/man/ASRange_new.3
new file mode 100644
index 00000000000..6aa33f2c791
--- /dev/null
+++ b/lib/libcrypto/man/ASRange_new.3
@@ -0,0 +1,257 @@
+.\" $OpenBSD: ASRange_new.3,v 1.1 2023/09/25 11:59:10 tb Exp $
+.\"
+.\" Copyright (c) 2023 Theo Buehler <tb@openbsd.org>
+.\"
+.\" 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 25 2023 $
+.Dt ASRANGE_NEW 3
+.Os
+.Sh NAME
+.Nm ASRange_new ,
+.Nm ASRange_free ,
+.Nm d2i_ASRange ,
+.Nm i2d_ASRange ,
+.Nm ASIdOrRange_new ,
+.Nm ASIdOrRange_free ,
+.Nm d2i_ASIdOrRange ,
+.Nm i2d_ASIdOrRange
+.Nd Autonomous system identifiers and ranges
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft "ASRange *"
+.Fn ASRange_new void
+.Ft void
+.Fn ASRange_free "ASRange *"
+.Ft ASRange *
+.Fo d2i_ASRange
+.Fa "ASRange **asrange"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASRange
+.Fa "ASRange *asrange"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft "ASIdOrRange *"
+.Fn ASIdOrRange_new void
+.Ft void
+.Fn ASIdOrRange_free "ASIdOrRange *aor"
+.Ft ASIdOrRange *
+.Fo d2i_ASIdOrRange
+.Fa "ASIdOrRange **aor"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASIdOrRange
+.Fa "ASIdOrRange *aor"
+.Fa "unsigned char **der_out"
+.Fc
+.Sh DESCRIPTION
+.Vt ASRange
+and
+.Vt ASIdOrRange
+are building blocks of the RFC 3779
+.Vt ASIdentifiers
+type representing the 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 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.
+.Pp
+The
+.Vt ASRange
+type defined in RFC 3779 section 3.2.3.8 is implemented as
+.Bd -literal -offset indent
+typedef struct ASRange_st {
+	ASN1_INTEGER *min;
+	ASN1_INTEGER *max;
+} ASRange;
+.Ed
+.Pp
+It represents the closed range [min,max] of AS identifiers between
+.Fa min
+and
+.Fa max ,
+where
+.Fa min
+should be strictly smaller than
+.Fa max .
+.Pp
+.Fn ASRange_new
+allocates a new
+.Vt ASRange
+object with allocated, empty
+.Fa min
+and
+.Fa max ,
+thus representing the invalid range [0,0].
+.Pp
+.Fn ASRange_free
+frees
+.Fa asrange
+including any data contained in it.
+If
+.Fa asrange
+is
+.Dv NULL ,
+no action occurs.
+.Pp
+The
+.Vt ASIdOrRange
+type defined in RFC 3779 section 3.2.3.5 is implemented as
+.Bd -literal -offset indent
+typedef struct ASIdOrRange_st {
+	int type;
+	union {
+		ASN1_INTEGER *id;
+		ASRange *range;
+	} u;
+} ASIdOrRange;
+.Ed
+.Pp
+representing an individual AS identifier or a range.
+When populating an
+.Vt ASIdOrRange
+object by hand, its
+.Fa type
+should be set to
+.Dv ASIdOrRange_id
+or
+.Dv ASIdOrRange_range
+to indicate which member of the union
+.Fa u
+is valid.
+.Pp
+.Fn ASIdOrRange_new
+returns a new
+.Vt ASIdOrRange
+object with invalid type and
+.Dv NULL
+members of the union
+.Fa u .
+.Pp
+.Fn ASIdOrRange_free
+frees
+.Fa aor
+including any data contained in it,
+provided
+.Fa type
+is set correctly.
+If
+.Fa asrange
+is
+.Dv NULL ,
+no action occurs.
+.Pp
+.Fn d2i_ASRange ,
+.Fn i2d_ASRange ,
+.Fn d2i_ASIdOrRange ,
+and
+.Fn i2d_ASIdOrRange
+decode and encode ASN.1
+.Vt ASRange
+and
+.Vt ASIdOrRange
+objects.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
+In order for the encoding produced by
+.Fn i2d_ASRange
+to be correct,
+.Fa min
+must be strictly less than
+.Fa max .
+Similarly for
+.Fn i2d_ASIdOrRange
+and an
+.Fa ASIdOrRange
+object of
+.Fa type
+.Dv ASIdOrRange_range .
+.Sh RETURN VALUES
+.Fn ASRange_new
+returns a new
+.Vt ASRange
+object or
+.Dv NULL
+if an error occurs.
+.Pp
+.Fn ASIdOrRange_new
+returns a new, empty
+.Vt ASIdOrRange
+object or
+.Dv NULL
+if an error occurs.
+.Pp
+The encoding functions
+.Fn d2i_ASRange
+and
+.Fn d2i_ASIdOrRange
+return an
+.Vt ASRange
+or an
+.Vt ASIdOrRange
+object, respectively,
+or
+.Dv NULL
+if an error occurs.
+.Pp
+The encoding functions
+.Fn i2d_ASRange
+and
+.Fn i2d_ASIdOrRange
+return the number of bytes successfully encoded
+or a value <= 0 if an error occurs.
+.Sh SEE ALSO
+.Xr ASIdentifiers_new 3 ,
+.Xr BN_set_word 3 ,
+.Xr BN_to_ASN1_INTEGER 3 ,
+.Xr crypto 3 ,
+.Xr s2i_ASN1_INTEGER 3 ,
+.Xr X509_new 3 ,
+.Xr X509v3_asid_add_id_or_range 3 ,
+.Xr X509v3_asid_is_canonical 3
+.Sh STANDARDS
+RFC 3779: X.509 Extensions for IP Addresses and AS Identifiers:
+.Bl -dash -compact
+.It
+section 3.2.3: Syntax
+.It
+section 3.2.3.5: Type ASIdOrRange
+.It
+section 3.2.3.6: Element id
+.It
+section 3.2.3.7: Element range
+.It
+section 3.2.3.8: Type ASRange
+.It
+section 3.2.3.9: Elements min and max
+.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/Makefile b/lib/libcrypto/man/Makefile
index ccf0be63feb..2ccc06895f2 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.269 2023/09/25 01:14:34 tb Exp $
+# $OpenBSD: Makefile,v 1.270 2023/09/25 11:59:10 tb Exp $
 
 .include <bsd.own.mk>
 
@@ -6,6 +6,7 @@ MAN=	\
 	ACCESS_DESCRIPTION_new.3 \
 	AES_encrypt.3 \
 	ASIdentifiers_new.3 \
+	ASRange_new.3 \
 	ASN1_BIT_STRING_set.3 \
 	ASN1_INTEGER_get.3 \
 	ASN1_NULL_new.3 \
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index f2615cd5bd5..42a29a0183b 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.38 2023/09/25 01:14:34 tb Exp $
+.\" $OpenBSD: X509_new.3,v 1.39 2023/09/25 11:59:10 tb Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -194,6 +194,7 @@ or
 if an error occurs.
 .Sh SEE ALSO
 .Xr ASIdentifiers_new 3 ,
+.Xr ASRange_new 3 ,
 .Xr AUTHORITY_KEYID_new 3 ,
 .Xr BASIC_CONSTRAINTS_new 3 ,
 .Xr crypto 3 ,