From 5e8c7fef518f5e540c2f4503a27dc39e214a2fd0 Mon Sep 17 00:00:00 2001 From: schwarze Date: Fri, 22 Oct 2021 15:50:19 +0000 Subject: [PATCH] new manual page EVP_PKEY_add1_attr(3) documenting nine functions for associating X.501 Attributes with private keys --- lib/libcrypto/man/EVP_PKEY_add1_attr.3 | 188 +++++++++++++++++++++++++ lib/libcrypto/man/EVP_PKEY_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/PKCS12_create.3 | 5 +- lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 3 +- lib/libcrypto/man/X509at_add1_attr.3 | 3 +- lib/libcrypto/man/X509at_get_attr.3 | 3 +- 7 files changed, 202 insertions(+), 8 deletions(-) create mode 100644 lib/libcrypto/man/EVP_PKEY_add1_attr.3 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 +.\" +.\" 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 @@ -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 .\" @@ -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 .\" @@ -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 .\" @@ -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 , -- 2.20.1