new manual page PKCS8_pkey_set0(3)

documenting four PKCS#8 PrivateKeyInfo accessors

6 files changed, 177 insertions, 9 deletions

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 <bsd.own.mk>
 
@@ -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 <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: 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 <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 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 <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 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 <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 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 <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 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 ,