Add initial documentation for the RFC 3779 API

This documents the part of the API that allows building the two
extensions. It is all very complicated and the bug density is
quite high. Surely there's lots of room for improvement, but
I've been sitting way too long on versions of these. I'll never
finish. Let's fix and improve in tree.

1 files changed, 129 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/ASIdentifiers_new.3 b/src/lib/libcrypto/man/ASIdentifiers_new.3
new file mode 100644
index 0000000000..828cda6ec6
--- /dev/null
+++ b/src/lib/libcrypto/man/ASIdentifiers_new.3
@@ -0,0 +1,129 @@
+.\" $OpenBSD: ASIdentifiers_new.3,v 1.1 2023/09/25 01:14:34 tb Exp $
+.\"
+.\" Copyright (c) 2021 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 ASIDENTIFIERS_NEW 3
+.Os
+.Sh NAME
+.Nm ASIdentifiers_new ,
+.Nm ASIdentifiers_free ,
+.Nm d2i_ASIdentifiers ,
+.Nm i2d_ASIdentifiers
+.Nd X509v3 certificate extension for autonomous system identifier delegation
+.Sh SYNOPSIS
+.In openssl/x509v3.h
+.Ft ASIdentifiers *
+.Fo ASIdentifiers_new
+.Fa "void"
+.Fc
+.Ft void
+.Fo ASIdentifiers_free
+.Fa "ASIdentifiers *asid"
+.Fc
+.Ft ASIdentifiers *
+.Fo d2i_ASIdentifiers
+.Fa "ASIdentifiers **asid"
+.Fa "const unsigned char **in"
+.Fa "long len"
+.Fc
+.Ft int
+.Fo i2d_ASIdentifiers
+.Fa "ASIdentifiers *asid"
+.Fa "unsigned char **out"
+.Fc
+.Sh DESCRIPTION
+RFC 3779 defines two X.509v3 certificate extensions that allow the
+delegation of
+IP address blocks and autonomous system (AS) identifiers
+from the issuer to the subject of the certificate.
+An
+.Vt ASIdentifiers
+object contains collections of individual AS numbers and
+ranges of AS numbers to be delegated.
+.Pp
+.Fn ASIdentifiers_new
+allocates and initializes a new, empty
+.Vt ASIdentifiers
+object that can be populated with
+.Xr X509v3_asid_add_id_or_range 3 .
+.Pp
+.Fn ASIdentifiers_free
+frees
+.Fa asid
+including any data contained in it.
+If
+.Fa asid
+is
+.Dv NULL ,
+no action occurs.
+.Pp
+.Fn d2i_ASIdentifiers
+and
+.Fn i2d_ASIdentifiers
+decode and encode ASN.1
+.Vt ASIdentifiers
+structures as defined in RFC 3779, section 3.2.3.1.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
+In order for the encoding produced by
+.Fn d2i_ASIdentifiers
+to conform to RFC 3779,
+.Fa asid
+must be in
+.Dq canonical form ,
+see
+.Xr X509v3_asid_canonize 3 .
+.Sh RETURN VALUES
+.Fn ASIdentifiers_new
+returns a new
+.Vt ASIdentifiers
+object or
+.Dv NULL
+on if an error occurs.
+.Pp
+.Fn d2i_ASIdentifiers
+returns an
+.Vt ASIdentifiers
+object or
+.Dv NULL
+on if a decoding or memory allocation error occurs.
+.Pp
+.Fn i2d_ASIdentifiers
+returns the number of bytes successfully encoded
+or a value <= 0 if an error occurs.
+.Sh SEE ALSO
+.Xr crypto 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: Autonomous System Identifier Delegation Extension
+.El
+.Pp
+RFC 7020: The Internet Numbers Registry System
+.Pp
+RFC 7249: Internet Numbers Registries
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.8e
+and have been available since
+.Ox 7.1 .
+.Sh BUGS
+There are no corresponding functions for the RFC 3779
+IP address blocks delegation extension represented by
+.Vt IPAddrBlocks .