From 43caf4b1b05709530aac94e6284f9b6f79ecfef0 Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 27 Oct 2021 14:54:07 +0000 Subject: [PATCH] new manual page X509_REQ_add_extensions(3) documenting six functions for extensions in certification requests --- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/X509_EXTENSION_set_object.3 | 3 +- lib/libcrypto/man/X509_REQ_add_extensions.3 | 141 ++++++++++++++++++ lib/libcrypto/man/X509_REQ_new.3 | 5 +- 4 files changed, 148 insertions(+), 4 deletions(-) create mode 100644 lib/libcrypto/man/X509_REQ_add_extensions.3 diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 4e7789dbb10..039a950d386 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/X509_EXTENSION_set_object.3 b/lib/libcrypto/man/X509_EXTENSION_set_object.3 index fb937b59ec0..c67077b57f0 100644 --- a/lib/libcrypto/man/X509_EXTENSION_set_object.3 +++ b/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/lib/libcrypto/man/X509_REQ_add_extensions.3 b/lib/libcrypto/man/X509_REQ_add_extensions.3 new file mode 100644 index 00000000000..8610edf8cab --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/X509_REQ_new.3 b/lib/libcrypto/man/X509_REQ_new.3 index 16c6f0bd787..7396b3610c5 100644 --- a/lib/libcrypto/man/X509_REQ_new.3 +++ b/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 .\" @@ -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 , -- 2.20.1