From e2edaa2ebb015e04f411ce1bb8ea27f7d4baccbc Mon Sep 17 00:00:00 2001 From: tb Date: Mon, 25 Sep 2023 11:59:10 +0000 Subject: [PATCH] New manual page documenting the usual four ASN.1 functions for both ASRange and ASIdOrRange --- lib/libcrypto/man/ASIdentifiers_new.3 | 3 +- lib/libcrypto/man/ASRange_new.3 | 257 ++++++++++++++++++++++++++ lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_new.3 | 3 +- 4 files changed, 263 insertions(+), 3 deletions(-) create mode 100644 lib/libcrypto/man/ASRange_new.3 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 .\" @@ -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 +.\" +.\" 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 @@ -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 , -- 2.20.1