new manual page X509_REQ_add1_attr(3) documenting nine functions

for X.501 Attributes in PKCS#10 certification requests

6 files changed, 199 insertions, 8 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index c697734c7ee..6d83257fe7d 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.202 2021/10/25 15:23:50 tb Exp $
+# $OpenBSD: Makefile,v 1.203 2021/10/26 12:56:48 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -303,6 +303,7 @@ MAN=	\
 	X509_PKEY_new.3 \
 	X509_PUBKEY_new.3 \
 	X509_PURPOSE_set.3 \
+	X509_REQ_add1_attr.3 \
 	X509_REQ_new.3 \
 	X509_REVOKED_new.3 \
 	X509_SIG_new.3 \
diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3
index a01b465c043..5dcdc6e214a 100644
--- a/lib/libcrypto/man/X509_ATTRIBUTE_new.3
+++ b/lib/libcrypto/man/X509_ATTRIBUTE_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.15 2021/10/25 12:25:14 schwarze Exp $
+.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.16 2021/10/26 12:56:48 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 25 2021 $
+.Dd $Mdocdate: October 26 2021 $
 .Dt X509_ATTRIBUTE_NEW 3
 .Os
 .Sh NAME
@@ -121,6 +121,7 @@ fails on
 .Xr X509_ATTRIBUTE_set1_object 3 ,
 .Xr X509_EXTENSION_new 3 ,
 .Xr X509_new 3 ,
+.Xr X509_REQ_add1_attr 3 ,
 .Xr X509_REQ_new 3 ,
 .Xr X509at_add1_attr 3 ,
 .Xr X509at_get_attr 3
diff --git a/lib/libcrypto/man/X509_REQ_add1_attr.3 b/lib/libcrypto/man/X509_REQ_add1_attr.3
new file mode 100644
index 00000000000..c75bffeb4fa
--- /dev/null
+++ b/lib/libcrypto/man/X509_REQ_add1_attr.3
@@ -0,0 +1,186 @@
+.\" $OpenBSD: X509_REQ_add1_attr.3,v 1.1 2021/10/26 12:56:48 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 26 2021 $
+.Dt X509_REQ_ADD1_ATTR 3
+.Os
+.Sh NAME
+.Nm X509_REQ_add1_attr ,
+.Nm X509_REQ_add1_attr_by_OBJ ,
+.Nm X509_REQ_add1_attr_by_NID ,
+.Nm X509_REQ_add1_attr_by_txt ,
+.Nm X509_REQ_delete_attr ,
+.Nm X509_REQ_get_attr ,
+.Nm X509_REQ_get_attr_count ,
+.Nm X509_REQ_get_attr_by_OBJ ,
+.Nm X509_REQ_get_attr_by_NID
+.Nd X.501 Attributes of PKCS#10 certification requests
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo X509_REQ_add1_attr
+.Fa "X509_REQ *req"
+.Fa "X509_ATTRIBUTE *attr"
+.Fc
+.Ft int
+.Fo X509_REQ_add1_attr_by_OBJ
+.Fa "X509_REQ *req"
+.Fa "const ASN1_OBJECT *obj"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo X509_REQ_add1_attr_by_NID
+.Fa "X509_REQ *req"
+.Fa "int nid"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo X509_REQ_add1_attr_by_txt
+.Fa "X509_REQ *req"
+.Fa "const char *name"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft X509_ATTRIBUTE *
+.Fo X509_REQ_delete_attr
+.Fa "X509_REQ *req"
+.Fa "int index"
+.Fc
+.Ft X509_ATTRIBUTE *
+.Fo X509_REQ_get_attr
+.Fa "const X509_REQ *req"
+.Fa "int index"
+.Fc
+.Ft int
+.Fo X509_REQ_get_attr_count
+.Fa "const X509_REQ *req"
+.Fc
+.Ft int
+.Fo X509_REQ_get_attr_by_OBJ
+.Fa "const X509_REQ *req"
+.Fa "const ASN1_OBJECT *obj"
+.Fa "int start_after"
+.Fc
+.Ft int
+.Fo X509_REQ_get_attr_by_NID
+.Fa "const X509_REQ *req"
+.Fa "int nid"
+.Fa "int start_after"
+.Fc
+.Sh DESCRIPTION
+These functions support associating an array of X.501 Attributes
+with a PKCS#10 certification request.
+.Pp
+.Fn X509_REQ_add1_attr
+appends a deep copy of the
+.Fa attr
+using
+.Xr X509at_add1_attr 3 .
+.Pp
+.Fn X509_REQ_add1_attr_by_OBJ ,
+.Fn X509_REQ_add1_attr_by_NID ,
+and
+.Fn X509_REQ_add1_attr_by_txt
+create a new X.501 Attribute object using
+.Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
+.Xr X509_ATTRIBUTE_create_by_NID 3 ,
+or
+.Xr X509_ATTRIBUTE_create_by_txt 3 ,
+respectively, and append it using
+.Xr X509at_add1_attr 3 .
+.Pp
+.Fn X509_REQ_delete_attr
+deletes the attribute with the zero-based
+.Fa index
+using
+.Xr X509at_delete_attr 3 .
+.Pp
+.Fn X509_REQ_get_attr
+returns the attribute with the zero-based
+.Fa index
+using
+.Xr X509at_get_attr 3 .
+.Pp
+.Fn X509_REQ_get_attr_count
+returns the number of attributes currently associated with
+.Fa req
+using
+.Xr X509at_get_attr_count 3 .
+.Pp
+.Fn X509_REQ_get_attr_by_OBJ
+and
+.Fn X509_REQ_get_attr_by_NID
+search for an attribute of the type
+.Fa obj
+or
+.Fa nid
+using
+.Xr X509at_get_attr_by_OBJ 3
+or
+.Xr X509at_get_attr_by_NID 3 ,
+respectively.
+.Sh RETURN VALUES
+.Fn X509_REQ_add1_attr ,
+.Fn X509_REQ_add1_attr_by_OBJ ,
+.Fn X509_REQ_add1_attr_by_NID ,
+and
+.Fn X509_REQ_add1_attr_by_txt
+return 1 for success or 0 for failure.
+.Pp
+.Fn X509_REQ_delete_attr
+and
+.Fn X509_REQ_get_attr
+return the deleted or requested attribute or
+.Dv NULL
+if the requested index is negative or greater than or equal to
+the current number of attributes associated with
+.Fa req .
+.Pp
+.Fn X509_REQ_get_attr_count
+returns the current number of attributes.
+.Pp
+.Fn X509_REQ_get_attr_by_OBJ
+and
+.Fn X509_REQ_get_attr_by_NID
+return the index of the first attribute that has an index greater than
+.Fa start_after
+and a type matching
+.Fa obj
+or
+.Fa nid ,
+respectively, or \-1 on failure.
+In addition,
+.Fn X509_REQ_get_attr_by_NID
+returns \-2 if
+.Xr OBJ_nid2obj 3
+fails on the requested
+.Fa nid .
+.Sh SEE ALSO
+.Xr OBJ_nid2obj 3 ,
+.Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
+.Xr X509_ATTRIBUTE_new 3 ,
+.Xr X509_REQ_new 3 ,
+.Xr X509at_add1_attr 3 ,
+.Xr X509at_get_attr 3
+.Sh HISTORY
+These funtions 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 76d3d352779..16c6f0bd787 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.7 2021/10/26 10:50:08 schwarze Exp $
+.\" $OpenBSD: X509_REQ_new.3,v 1.8 2021/10/26 12:56:48 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -98,6 +98,7 @@ if an error occurs.
 .Xr d2i_X509_REQ 3 ,
 .Xr PEM_read_X509_REQ 3 ,
 .Xr X509_new 3 ,
+.Xr X509_REQ_add1_attr 3 ,
 .Xr X509_REQ_check_private_key 3 ,
 .Xr X509_REQ_digest 3 ,
 .Xr X509_REQ_get0_signature 3 ,
diff --git a/lib/libcrypto/man/X509at_add1_attr.3 b/lib/libcrypto/man/X509at_add1_attr.3
index b501b1ca620..3d29c56ef96 100644
--- a/lib/libcrypto/man/X509at_add1_attr.3
+++ b/lib/libcrypto/man/X509at_add1_attr.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509at_add1_attr.3,v 1.4 2021/10/25 12:25:14 schwarze Exp $
+.\" $OpenBSD: X509at_add1_attr.3,v 1.5 2021/10/26 12:56:48 schwarze Exp $
 .\"
 .\" Copyright (c) 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 25 2021 $
+.Dd $Mdocdate: October 26 2021 $
 .Dt X509AT_ADD1_ATTR 3
 .Os
 .Sh NAME
@@ -126,6 +126,7 @@ is negative or greater than or equal to the number of objects in
 .Xr STACK_OF 3 ,
 .Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
 .Xr X509_ATTRIBUTE_new 3 ,
+.Xr X509_REQ_add1_attr 3 ,
 .Xr X509at_get_attr 3
 .Sh HISTORY
 These functions first appeared in OpenSSL 0.9.5
diff --git a/lib/libcrypto/man/X509at_get_attr.3 b/lib/libcrypto/man/X509at_get_attr.3
index 45b93f92436..418302b1b3f 100644
--- a/lib/libcrypto/man/X509at_get_attr.3
+++ b/lib/libcrypto/man/X509at_get_attr.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509at_get_attr.3,v 1.4 2021/10/25 12:25:14 schwarze Exp $
+.\" $OpenBSD: X509at_get_attr.3,v 1.5 2021/10/26 12:56:48 schwarze Exp $
 .\"
 .\" Copyright (c) 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 25 2021 $
+.Dd $Mdocdate: October 26 2021 $
 .Dt X509AT_GET_ATTR 3
 .Os
 .Sh NAME
@@ -145,6 +145,7 @@ on failure.
 .Xr STACK_OF 3 ,
 .Xr X509_ATTRIBUTE_get0_data 3 ,
 .Xr X509_ATTRIBUTE_new 3 ,
+.Xr X509_REQ_get_attr 3 ,
 .Xr X509at_add1_attr 3
 .Sh HISTORY
 .Fn X509at_get_attr ,