new manual page EVP_PKEY_add1_attr(3) documenting nine functions

for associating X.501 Attributes with private keys

7 files changed, 202 insertions, 8 deletions

diff --git a/lib/libcrypto/man/EVP_PKEY_add1_attr.3 b/lib/libcrypto/man/EVP_PKEY_add1_attr.3
new file mode 100644
index 00000000000..8d30c40b68d
--- /dev/null
+++ b/lib/libcrypto/man/EVP_PKEY_add1_attr.3
@@ -0,0 +1,188 @@
+.\" $OpenBSD: EVP_PKEY_add1_attr.3,v 1.1 2021/10/22 15:50:19 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 22 2021 $
+.Dt EVP_PKEY_ADD1_ATTR 3
+.Os
+.Sh NAME
+.Nm EVP_PKEY_add1_attr ,
+.Nm EVP_PKEY_add1_attr_by_OBJ ,
+.Nm EVP_PKEY_add1_attr_by_NID ,
+.Nm EVP_PKEY_add1_attr_by_txt ,
+.Nm EVP_PKEY_delete_attr ,
+.Nm EVP_PKEY_get_attr ,
+.Nm EVP_PKEY_get_attr_count ,
+.Nm EVP_PKEY_get_attr_by_OBJ ,
+.Nm EVP_PKEY_get_attr_by_NID
+.Nd X.501 Attributes of private keys
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo EVP_PKEY_add1_attr
+.Fa "EVP_PKEY *key"
+.Fa "X509_ATTRIBUTE *attr"
+.Fc
+.Ft int
+.Fo EVP_PKEY_add1_attr_by_OBJ
+.Fa "EVP_PKEY *key"
+.Fa "const ASN1_OBJECT *obj"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo EVP_PKEY_add1_attr_by_NID
+.Fa "EVP_PKEY *key"
+.Fa "int nid"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo EVP_PKEY_add1_attr_by_txt
+.Fa "EVP_PKEY *key"
+.Fa "const char *name"
+.Fa "int type"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft X509_ATTRIBUTE *
+.Fo EVP_PKEY_delete_attr
+.Fa "EVP_PKEY *key"
+.Fa "int index"
+.Fc
+.Ft X509_ATTRIBUTE *
+.Fo EVP_PKEY_get_attr
+.Fa "const EVP_PKEY *key"
+.Fa "int index"
+.Fc
+.Ft int
+.Fo EVP_PKEY_get_attr_count
+.Fa "const EVP_PKEY *key"
+.Fc
+.Ft int
+.Fo EVP_PKEY_get_attr_by_OBJ
+.Fa "const EVP_PKEY *key"
+.Fa "const ASN1_OBJECT *obj"
+.Fa "int start_after"
+.Fc
+.Ft int
+.Fo EVP_PKEY_get_attr_by_NID
+.Fa "const EVP_PKEY *key"
+.Fa "int nid"
+.Fa "int start_after"
+.Fc
+.Sh DESCRIPTION
+These functions support associating an array of X.501 Attributes
+with a private key.
+Such attributes can for example be included in PKCS#12 structures.
+.Pp
+.Fn EVP_PKEY_add1_attr
+appends a deep copy of the
+.Fa attr
+using
+.Xr X509at_add1_attr 3 .
+.Pp
+.Fn EVP_PKEY_add1_attr_by_OBJ ,
+.Fn EVP_PKEY_add1_attr_by_NID ,
+and
+.Fn EVP_PKEY_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 EVP_PKEY_delete_attr
+deletes the attribute with the zero-based
+.Fa index
+using
+.Xr X509at_delete_attr 3 .
+.Pp
+.Fn EVP_PKEY_get_attr
+returns the attribute with the zero-based
+.Fa index
+using
+.Xr X509at_get_attr 3 .
+.Pp
+.Fn EVP_PKEY_get_attr_count
+returns the number of attributes currently associated with the
+.Fa key
+using
+.Xr X509at_get_attr_count 3 .
+.Pp
+.Fn EVP_PKEY_get_attr_by_OBJ
+and
+.Fn EVP_PKEY_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 EVP_PKEY_add1_attr ,
+.Fn EVP_PKEY_add1_attr_by_OBJ ,
+.Fn EVP_PKEY_add1_attr_by_NID ,
+and
+.Fn EVP_PKEY_add1_attr_by_txt
+return 1 for success or 0 for failure.
+.Pp
+.Fn EVP_PKEY_delete_attr
+and
+.Fn X509at_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 the
+.Fa key .
+.Pp
+.Fn EVP_PKEY_get_attr_count
+returns the current number of attributes.
+.Pp
+.Fn EVP_PKEY_get_attr_by_OBJ
+and
+.Fn EVP_PKEY_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 EVP_PKEY_get_attr_by_NID
+returns \-2 if
+.Xr OBJ_nid2obj 3
+fails on the requested
+.Fa nid .
+.Sh SEE ALSO
+.Xr EVP_PKEY_new 3 ,
+.Xr OBJ_nid2obj 3 ,
+.Xr PKCS12_create 3 ,
+.Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
+.Xr X509_ATTRIBUTE_new 3 ,
+.Xr X509at_add1_attr 3 ,
+.Xr X509at_get_attr 3
+.Sh HISTORY
+These funtions first appeared in OpenSSL 0.9.8
+and have been available since
+.Ox 4.5 .
diff --git a/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3
index 76eb3459413..754fe94e608 100644
--- a/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/lib/libcrypto/man/EVP_PKEY_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_new.3,v 1.14 2021/10/19 17:42:49 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_new.3,v 1.15 2021/10/22 15:50:19 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\" selective merge up to: OpenSSL df75c2bf Dec 9 01:02:36 2018 +0100
 .\"
@@ -50,7 +50,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: October 19 2021 $
+.Dd $Mdocdate: October 22 2021 $
 .Dt EVP_PKEY_NEW 3
 .Os
 .Sh NAME
@@ -184,6 +184,7 @@ returns 1 for success or 0 for failure.
 .Xr CMAC_Init 3 ,
 .Xr d2i_PrivateKey 3 ,
 .Xr evp 3 ,
+.Xr EVP_PKEY_add1_attr 3 ,
 .Xr EVP_PKEY_asn1_new 3 ,
 .Xr EVP_PKEY_cmp 3 ,
 .Xr EVP_PKEY_CTX_new 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 74b3a251afe..6179d3157b6 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.198 2021/10/22 13:29:41 schwarze Exp $
+# $OpenBSD: Makefile,v 1.199 2021/10/22 15:50:19 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -159,6 +159,7 @@ MAN=	\
 	EVP_EncodeInit.3 \
 	EVP_EncryptInit.3 \
 	EVP_OpenInit.3 \
+	EVP_PKEY_add1_attr.3 \
 	EVP_PKEY_asn1_new.3 \
 	EVP_PKEY_asn1_get_count.3 \
 	EVP_PKEY_CTX_ctrl.3 \
diff --git a/lib/libcrypto/man/PKCS12_create.3 b/lib/libcrypto/man/PKCS12_create.3
index 1f44ef9b67e..d19a6f3e44f 100644
--- a/lib/libcrypto/man/PKCS12_create.3
+++ b/lib/libcrypto/man/PKCS12_create.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS12_create.3,v 1.10 2021/07/09 12:07:27 schwarze Exp $
+.\" $OpenBSD: PKCS12_create.3,v 1.11 2021/10/22 15:50:19 schwarze Exp $
 .\" full merge up to: OpenSSL 05ea606a May 20 20:52:46 2016 -0400
 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 9 2021 $
+.Dd $Mdocdate: October 22 2021 $
 .Dt PKCS12_CREATE 3
 .Os
 .Sh NAME
@@ -165,6 +165,7 @@ if an error occurred.
 .Sh SEE ALSO
 .Xr crypto 3 ,
 .Xr d2i_PKCS12 3 ,
+.Xr EVP_PKEY_add1_attr 3 ,
 .Xr PKCS12_new 3 ,
 .Xr PKCS12_newpass 3 ,
 .Xr PKCS12_parse 3 ,
diff --git a/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/lib/libcrypto/man/X509_ATTRIBUTE_new.3
index 1d059acceac..5e4fe27efe1 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.13 2021/10/22 13:29:41 schwarze Exp $
+.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.14 2021/10/22 15:50:19 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -111,6 +111,7 @@ fails on
 .Fa nid .
 .Sh SEE ALSO
 .Xr d2i_X509_ATTRIBUTE 3 ,
+.Xr EVP_PKEY_add1_attr 3 ,
 .Xr OBJ_nid2obj 3 ,
 .Xr PKCS12_SAFEBAG_new 3 ,
 .Xr PKCS7_add_attribute 3 ,
diff --git a/lib/libcrypto/man/X509at_add1_attr.3 b/lib/libcrypto/man/X509at_add1_attr.3
index cb5999a7029..823cf5b4f3d 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.1 2021/10/22 13:29:41 schwarze Exp $
+.\" $OpenBSD: X509at_add1_attr.3,v 1.2 2021/10/22 15:50:19 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -120,6 +120,7 @@ or if the requested
 is negative or greater than or equal to the number of objects in
 .Pf * Fa attrs .
 .Sh SEE ALSO
+.Xr EVP_PKEY_add1_attr 3 ,
 .Xr OBJ_nid2obj 3 ,
 .Xr STACK_OF 3 ,
 .Xr X509_ATTRIBUTE_create_by_OBJ 3 ,
diff --git a/lib/libcrypto/man/X509at_get_attr.3 b/lib/libcrypto/man/X509at_get_attr.3
index 64a2d8d4790..85340343171 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.2 2021/10/22 13:29:41 schwarze Exp $
+.\" $OpenBSD: X509at_get_attr.3,v 1.3 2021/10/22 15:50:19 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -139,6 +139,7 @@ or
 .Dv NULL
 on failure.
 .Sh SEE ALSO
+.Xr EVP_PKEY_get_attr 3 ,
 .Xr OBJ_nid2obj 3 ,
 .Xr STACK_OF 3 ,
 .Xr X509_ATTRIBUTE_get0_data 3 ,