From 2236870d7e58da64d32e11fed5c33a96b999ab63 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Mon, 25 Oct 2021 12:25:14 +0000 Subject: new manual page PKCS8_pkey_set0(3) documenting four PKCS#8 PrivateKeyInfo accessors --- src/lib/libcrypto/man/Makefile | 3 +- src/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 | 6 +- src/lib/libcrypto/man/PKCS8_pkey_set0.3 | 162 ++++++++++++++++++++++++ src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 | 5 +- src/lib/libcrypto/man/X509at_add1_attr.3 | 5 +- src/lib/libcrypto/man/X509at_get_attr.3 | 5 +- 6 files changed, 177 insertions(+), 9 deletions(-) create mode 100644 src/lib/libcrypto/man/PKCS8_pkey_set0.3 (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile index 6179d3157b..820957dfa9 100644 --- a/src/lib/libcrypto/man/Makefile +++ b/src/lib/libcrypto/man/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.199 2021/10/22 15:50:19 schwarze Exp $ +# $OpenBSD: Makefile,v 1.200 2021/10/25 12:25:14 schwarze Exp $ .include @@ -237,6 +237,7 @@ MAN= \ PKCS7_sign_add_signer.3 \ PKCS7_verify.3 \ PKCS8_PRIV_KEY_INFO_new.3 \ + PKCS8_pkey_set0.3 \ PKEY_USAGE_PERIOD_new.3 \ POLICYINFO_new.3 \ PROXY_POLICY_new.3 \ diff --git a/src/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 b/src/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 index 91cd25d425..639eceeded 100644 --- a/src/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 +++ b/src/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: PKCS8_PRIV_KEY_INFO_new.3,v 1.4 2019/06/06 01:06:59 schwarze Exp $ +.\" $OpenBSD: PKCS8_PRIV_KEY_INFO_new.3,v 1.5 2021/10/25 12:25:14 schwarze Exp $ .\" .\" Copyright (c) 2016 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: June 6 2019 $ +.Dd $Mdocdate: October 25 2021 $ .Dt PKCS8_PRIV_KEY_INFO_NEW 3 .Os .Sh NAME @@ -48,10 +48,12 @@ object or .Dv NULL if an error occurs. .Sh SEE ALSO +.Xr d2i_PKCS8_PRIV_KEY_INFO 3 , .Xr d2i_PKCS8PrivateKey_bio 3 , .Xr EVP_PKEY_asn1_set_private 3 , .Xr PEM_read_PKCS8_PRIV_KEY_INFO 3 , .Xr PKCS12_parse 3 , +.Xr PKCS8_pkey_set0 3 , .Xr X509_ATTRIBUTE_new 3 .Sh STANDARDS RFC 5208: PKCS#8: Private-Key Information Syntax Specification diff --git a/src/lib/libcrypto/man/PKCS8_pkey_set0.3 b/src/lib/libcrypto/man/PKCS8_pkey_set0.3 new file mode 100644 index 0000000000..c7e4fd0ea4 --- /dev/null +++ b/src/lib/libcrypto/man/PKCS8_pkey_set0.3 @@ -0,0 +1,162 @@ +.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.1 2021/10/25 12:25:14 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 25 2021 $ +.Dt PKCS8_PKEY_SET0 3 +.Os +.Sh NAME +.Nm PKCS8_pkey_set0 , +.Nm PKCS8_pkey_get0 , +.Nm PKCS8_pkey_add1_attr_by_NID , +.Nm PKCS8_pkey_get0_attrs +.Nd change and inspect PKCS#8 PrivateKeyInfo objects +.Sh SYNOPSIS +.In openssl/x509.h +.Ft int +.Fo PKCS8_pkey_set0 +.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" +.Fa "ASN1_OBJECT *aobj" +.Fa "int version" +.Fa "int ptype" +.Fa "void *pval" +.Fa "unsigned char *data" +.Fa "int len" +.Fc +.Ft int +.Fo PKCS8_pkey_get0 +.Fa "const ASN1_OBJECT **paobj" +.Fa "const unsigned char **pdata" +.Fa "int *plen" +.Fa "const X509_ALGOR **palgor" +.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" +.Fc +.Ft int +.Fo PKCS8_pkey_add1_attr_by_NID +.Fa "PKCS8_PRIV_KEY_INFO *keyinfo" +.Fa "int nid" +.Fa "int type" +.Fa "const unsigned char *data" +.Fa "int len" +.Fc +.Ft const STACK_OF(X509_ATTRIBUTE) * +.Fo PKCS8_pkey_get0_attrs +.Fa "const PKCS8_PRIV_KEY_INFO *keyinfo" +.Fc +.Sh DESCRIPTION +.Fn PKCS8_pkey_set0 +initializes the +.Fa keyinfo +object. +The algorithm is set to +.Fa aobj +with the associated parameter type +.Fa ptype +and parameter value +.Fa pval +using +.Xr X509_ALGOR_set0 3 , +replacing any previous information about the algorithm. +Unless +.Fa data +is +.Dv NULL , +the encoded private key is set to the +.Fa len +bytes starting at +.Fa data +using +.Xr ASN1_STRING_set0 3 , +not performing any validation. +If +.Fa data +is +.Dv NULL , +the key data remains unchanged. +If the +.Fa version +argument is greater than or equal to 0, it replaces any existing version; +otherwise, the version remains unchanged. +If +.Fa keyinfo +contains any attributes, they remain unchanged. +.Pp +.Fn PKCS8_pkey_get0 +retrieves some information from the +.Fa keyinfo +object. +Internal pointers to the algorithm OID, the +.Vt AlgorithmIdentifier , +and the encoded private key are stored in +.Pf * Fa paobj , +.Pf * Fa palgor , +and +.Pf * Fa pdata , +respectively. +.Dv NULL +pointers can be passed for any of these three arguments if the respective +information is not needed. +Unless +.Fa pdata +is +.Dv NULL , +.Pf * Fa plen +is set to the number of bytes in +.Pf * Fa pdata . +.Pp +.Fn PKCS8_pkey_add1_attr_by_NID +creates a new X.501 Attribute object using +.Xr X509_ATTRIBUTE_create_by_NID 3 +and appends it to the attributes of +.Fa keyinfo +using +.Xr X509at_add1_attr 3 . +.Sh RETURN VALUES +.Fn PKCS8_pkey_set0 +and +.Fn PKCS8_pkey_add1_attr_by_NID +return 1 for success or 0 for failure. +.Pp +.Fn PKCS8_pkey_get0 +always returns 1. +.Pp +.Fn PKCS8_pkey_get0_attrs +returns an internal pointer to the array of attributes associated with +.Fa keyinfo +or +.Dv NULL +if no attributes are set. +.Sh SEE ALSO +.Xr ASN1_STRING_set0 3 , +.Xr OBJ_nid2obj 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 , +.Xr STACK_OF 3 , +.Xr X509_ALGOR_new 3 , +.Xr X509_ATTRIBUTE_create_by_NID 3 , +.Xr X509_ATTRIBUTE_new 3 , +.Xr X509at_add1_attr 3 , +.Xr X509at_get_attr 3 +.Sh HISTORY +.Fn PKCS8_pkey_set0 +and +.Fn PKCS8_pkey_get0 +first appeared in OpenSSL 1.0.0 and have been available since +.Ox 4.9 . +.Pp +.Fn PKCS8_pkey_add1_attr_by_NID +and +.Fn PKCS8_pkey_get0_attrs +first appeared in OpenSSL 1.1.0 and have been available since +.Ox 6.4 . diff --git a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 index 5e4fe27efe..a01b465c04 100644 --- a/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 +++ b/src/lib/libcrypto/man/X509_ATTRIBUTE_new.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.14 2021/10/22 15:50:19 schwarze Exp $ +.\" $OpenBSD: X509_ATTRIBUTE_new.3,v 1.15 2021/10/25 12:25:14 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 22 2021 $ +.Dd $Mdocdate: October 25 2021 $ .Dt X509_ATTRIBUTE_NEW 3 .Os .Sh NAME @@ -115,6 +115,7 @@ fails on .Xr OBJ_nid2obj 3 , .Xr PKCS12_SAFEBAG_new 3 , .Xr PKCS7_add_attribute 3 , +.Xr PKCS8_pkey_get0_attrs 3 , .Xr PKCS8_PRIV_KEY_INFO_new 3 , .Xr X509_ATTRIBUTE_get0_object 3 , .Xr X509_ATTRIBUTE_set1_object 3 , diff --git a/src/lib/libcrypto/man/X509at_add1_attr.3 b/src/lib/libcrypto/man/X509at_add1_attr.3 index 0162b1f99f..b501b1ca62 100644 --- a/src/lib/libcrypto/man/X509at_add1_attr.3 +++ b/src/lib/libcrypto/man/X509at_add1_attr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509at_add1_attr.3,v 1.3 2021/10/24 07:08:20 jmc Exp $ +.\" $OpenBSD: X509at_add1_attr.3,v 1.4 2021/10/25 12:25:14 schwarze Exp $ .\" .\" Copyright (c) 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 24 2021 $ +.Dd $Mdocdate: October 25 2021 $ .Dt X509AT_ADD1_ATTR 3 .Os .Sh NAME @@ -122,6 +122,7 @@ is negative or greater than or equal to the number of objects in .Sh SEE ALSO .Xr EVP_PKEY_add1_attr 3 , .Xr OBJ_nid2obj 3 , +.Xr PKCS8_pkey_add1_attr_by_NID 3 , .Xr STACK_OF 3 , .Xr X509_ATTRIBUTE_create_by_OBJ 3 , .Xr X509_ATTRIBUTE_new 3 , diff --git a/src/lib/libcrypto/man/X509at_get_attr.3 b/src/lib/libcrypto/man/X509at_get_attr.3 index 8534034317..45b93f9243 100644 --- a/src/lib/libcrypto/man/X509at_get_attr.3 +++ b/src/lib/libcrypto/man/X509at_get_attr.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: X509at_get_attr.3,v 1.3 2021/10/22 15:50:19 schwarze Exp $ +.\" $OpenBSD: X509at_get_attr.3,v 1.4 2021/10/25 12:25:14 schwarze Exp $ .\" .\" Copyright (c) 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 22 2021 $ +.Dd $Mdocdate: October 25 2021 $ .Dt X509AT_GET_ATTR 3 .Os .Sh NAME @@ -141,6 +141,7 @@ on failure. .Sh SEE ALSO .Xr EVP_PKEY_get_attr 3 , .Xr OBJ_nid2obj 3 , +.Xr PKCS8_pkey_get0_attrs 3 , .Xr STACK_OF 3 , .Xr X509_ATTRIBUTE_get0_data 3 , .Xr X509_ATTRIBUTE_new 3 , -- cgit v1.2.3-55-g6feb