new manual page X509_REQ_add_extensions(3)

documenting six functions for extensions in certification requests

4 files changed, 148 insertions, 4 deletions

diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 4e7789dbb1..039a950d38 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.204 2021/10/26 18:11:04 tb Exp $
+# $OpenBSD: Makefile,v 1.205 2021/10/27 14:54:07 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -304,6 +304,7 @@ MAN=	\
         X509_PUBKEY_new.3 \
         X509_PURPOSE_set.3 \
         X509_REQ_add1_attr.3 \
+        X509_REQ_add_extensions.3 \
         X509_REQ_new.3 \
         X509_REVOKED_new.3 \
         X509_SIG_get0.3 \
diff --git a/src/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/src/lib/libcrypto/man/X509_EXTENSION_set_object.3
index fb937b59ec..c67077b57f 100644
--- a/src/lib/libcrypto/man/X509_EXTENSION_set_object.3
+++ b/src/lib/libcrypto/man/X509_EXTENSION_set_object.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: X509_EXTENSION_set_object.3,v 1.13 2021/10/27 11:24:47 schwarze Exp $
+.\"     $OpenBSD: X509_EXTENSION_set_object.3,v 1.14 2021/10/27 14:54:07 schwarze Exp $
 .\"     OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -288,6 +288,7 @@ pointer.
 .Xr X509_check_host 3 ,
 .Xr X509_check_issued 3 ,
 .Xr X509_get_extension_flags 3 ,
+.Xr X509_REQ_add_extensions 3 ,
 .Xr X509V3_EXT_print 3 ,
 .Xr X509V3_extensions_print 3 ,
 .Xr X509V3_get_d2i 3 ,
diff --git a/src/lib/libcrypto/man/X509_REQ_add_extensions.3 b/src/lib/libcrypto/man/X509_REQ_add_extensions.3
new file mode 100644
index 0000000000..8610edf8ca
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_REQ_add_extensions.3
@@ -0,0 +1,141 @@
+.\" $OpenBSD: X509_REQ_add_extensions.3,v 1.1 2021/10/27 14:54:07 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@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: October 27 2021 $
+.Dt X509_REQ_ADD_EXTENSIONS 3
+.Os
+.Sh NAME
+.Nm X509_REQ_add_extensions ,
+.Nm X509_REQ_add_extensions_nid ,
+.Nm X509_REQ_get_extensions ,
+.Nm X509_REQ_set_extension_nids ,
+.Nm X509_REQ_get_extension_nids ,
+.Nm X509_REQ_extension_nid
+.Nd extensions in certification requests
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo X509_REQ_add_extensions
+.Fa "X509_REQ *req"
+.Fa "STACK_OF(X509_EXTENSION) *extensions"
+.Fc
+.Ft int
+.Fo X509_REQ_add_extensions_nid
+.Fa "X509_REQ *req"
+.Fa "STACK_OF(X509_EXTENSION) *extensions"
+.Fa "int nid"
+.Fc
+.Ft STACK_OF(X509_EXTENSION) *
+.Fn X509_REQ_get_extensions "X509_REQ *req"
+.Ft void
+.Fn X509_REQ_set_extension_nids "int *nids"
+.Ft int *
+.Fn X509_REQ_get_extension_nids void
+.Ft int
+.Fn X509_REQ_extension_nid "int nid"
+.Sh DESCRIPTION
+.Fn X509_REQ_add_extensions
+encodes the array of
+.Fa extensions
+using
+.Xr i2d_X509_EXTENSIONS 3
+and adds a new X.501 Attribute object of the type
+.Dv NID_ext_req
+to
+.Fa req
+using the equivalent of
+.Xr X509_ATTRIBUTE_create_by_NID 3
+with a
+.Fa type
+of
+.Dv V_ASN1_SEQUENCE .
+.Pp
+.Fn X509_REQ_add_extensions_nid
+is identical except that the specified
+.Fa nid
+is used as the X.501 Attribute type instead of
+.Dv NID_ext_req .
+.Pp
+.Fn X509_REQ_get_extensions
+retrieves the first value of the first X.501 Attribute of appropriate type.
+By default, the attribute types
+.Dv NID_ext_req
+and
+.Dv NID_ms_ext_req
+are considered appropriate.
+.Pp
+.Fn X509_REQ_set_extension_nids
+replaces the list of attribute types that
+.Fn X509_REQ_get_extensions
+considers appropriate for storing extensions.
+The
+.Fa nids
+argument is interpreted as a pointer to the first element
+of a variable-sized array of
+.Vt int .
+The last element of the array has to be
+.Dv NID_undef .
+The array needs to remain valid until
+.Fn X509_REQ_set_extension_nids
+is called again with a different argument.
+.Pp
+.Fn X509_REQ_extension_nid
+checks whether
+.Fn X509_REQ_get_extensions
+regards the
+.Fa nid
+argument as a type appropriate for storing extensions.
+.Sh RETURN VALUES
+.Fn X509_REQ_add_extensions
+and
+.Fn X509_REQ_add_extensions_nid
+returns 1 for success or 0 for failure.
+.Pp
+.Fn X509_REQ_get_extensions
+returns a newly allocated array of ASN.1
+.Vt Extension
+objects or
+.Dv NULL
+if
+.Fa req
+is
+.Dv NULL ,
+does not contain
+.Vt CertificationRequestInfo ,
+contains no attribute of an appropriate type,
+or if decoding or memory allocation fails.
+.Pp
+.Fn X509_REQ_get_extension_nids
+returns the pointer installed with
+.Fn X509_REQ_set_extension_nids
+or a pointer to a static array
+.Brq Dv NID_ext_req , NID_ms_ext_req , NID_undef
+by default.
+.Pp
+.Fn X509_REQ_extension_nid
+returns 1 if
+.Fa nid
+is considered appropriate or 0 otherwise.
+.Sh SEE ALSO
+.Xr d2i_X509_EXTENSION 3 ,
+.Xr STACK_OF 3 ,
+.Xr X509_EXTENSION_new 3 ,
+.Xr X509_REQ_new 3 ,
+.Xr X509V3_extensions_print 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.5
+and have been available since
+.Ox 2.7 .
diff --git a/src/lib/libcrypto/man/X509_REQ_new.3 b/src/lib/libcrypto/man/X509_REQ_new.3
index 16c6f0bd78..7396b3610c 100644
--- a/src/lib/libcrypto/man/X509_REQ_new.3
+++ b/src/lib/libcrypto/man/X509_REQ_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_REQ_new.3,v 1.8 2021/10/26 12:56:48 schwarze Exp $
+.\" $OpenBSD: X509_REQ_new.3,v 1.9 2021/10/27 14:54:07 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2021 Ingo Schwarze <schwarze@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: October 26 2021 $
+.Dd $Mdocdate: October 27 2021 $
 .Dt X509_REQ_NEW 3
 .Os
 .Sh NAME
@@ -99,6 +99,7 @@ if an error occurs.
 .Xr PEM_read_X509_REQ 3 ,
 .Xr X509_new 3 ,
 .Xr X509_REQ_add1_attr 3 ,
+.Xr X509_REQ_add_extensions 3 ,
 .Xr X509_REQ_check_private_key 3 ,
 .Xr X509_REQ_digest 3 ,
 .Xr X509_REQ_get0_signature 3 ,