new manual page EVP_PKCS82PKEY(3), also documenting EVP_PKEY2PKCS8(3)

6 files changed, 77 insertions, 10 deletions

diff --git a/src/lib/libcrypto/man/EVP_PKCS82PKEY.3 b/src/lib/libcrypto/man/EVP_PKCS82PKEY.3
new file mode 100644
index 0000000000..5fed846fe6
--- /dev/null
+++ b/src/lib/libcrypto/man/EVP_PKCS82PKEY.3
@@ -0,0 +1,63 @@
+.\" $OpenBSD: EVP_PKCS82PKEY.3,v 1.1 2021/10/25 13:48:12 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 EVP_PKCS82PKEY 3
+.Os
+.Sh NAME
+.Nm EVP_PKCS82PKEY ,
+.Nm EVP_PKEY2PKCS8
+.Nd convert between EVP_PKEY and PKCS#8 PrivateKeyInfo
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft EVP_PKEY *
+.Fn EVP_PKCS82PKEY "const PKCS8_PRIV_KEY_INFO *keyinfo"
+.Ft PKCS8_PRIV_KEY_INFO *
+.Fn EVP_PKEY2PKCS8 "EVP_PKEY *pkey"
+.Sh DESCRIPTION
+.Fn EVP_PKCS82PKEY
+extracts the private key from a PKCS#8
+.Vt PrivateKeyInfo
+structure.
+.Pp
+.Fn EVP_PKEY2PKCS8
+creates a PKCS#8
+.Vt PrivateKeyInfo
+structure representing the private key contained in
+.Fa pkey .
+.Pp
+Supported algorithms include DH, DSA, EC, GOST2001, and RSA.
+Application programs can add additional algorithms using
+.Xr EVP_PKEY_asn1_add0 3 .
+.Sh RETURN VALUES
+These functions return a newly allocated object or
+.Dv NULL
+if the algorithm indicated in
+.Fa keyinfo
+or
+.Fa pkey
+is unsupported or if memory allocation, decoding, or encoding fails.
+.Sh SEE ALSO
+.Xr EVP_PKEY_asn1_add0 3 ,
+.Xr EVP_PKEY_base_id 3 ,
+.Xr EVP_PKEY_new 3 ,
+.Xr PKCS8_pkey_set0 3 ,
+.Xr PKCS8_PRIV_KEY_INFO_new 3 ,
+.Xr X509_ALGOR_get0 3
+.Sh HISTORY
+These functions first appeared in OpenSSL 0.9.3
+and have been available since
+.Ox 2.6 .
diff --git a/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3
index 5d915d0183..a363a9615f 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3
+++ b/src/lib/libcrypto/man/EVP_PKEY_asn1_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.5 2019/09/01 09:10:09 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.6 2021/10/25 13:48:12 schwarze Exp $
 .\" selective merge up to:
 .\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800
 .\"
@@ -49,8 +49,8 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 1 2019 $
-.Dt EVP_PKEY_ASN1_METHOD 3
+.Dd $Mdocdate: October 25 2021 $
+.Dt EVP_PKEY_ASN1_NEW 3
 .Os
 .Sh NAME
 .Nm EVP_PKEY_asn1_new ,
@@ -228,9 +228,9 @@ form private key to and from
 .Fa pk .
 They must return 0 on error, 1 on success.
 They are called by
-.Fn EVP_PKCS82PKEY
+.Xr EVP_PKCS82PKEY 3
 and
-.Fn EVP_PKEY2PKCS8 .
+.Xr EVP_PKEY2PKCS8 3 .
 .Pp
 The
 .Fn priv_print
diff --git a/src/lib/libcrypto/man/EVP_PKEY_new.3 b/src/lib/libcrypto/man/EVP_PKEY_new.3
index 754fe94e60..5850c63d25 100644
--- a/src/lib/libcrypto/man/EVP_PKEY_new.3
+++ b/src/lib/libcrypto/man/EVP_PKEY_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: EVP_PKEY_new.3,v 1.15 2021/10/22 15:50:19 schwarze Exp $
+.\" $OpenBSD: EVP_PKEY_new.3,v 1.16 2021/10/25 13:48:12 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 22 2021 $
+.Dd $Mdocdate: October 25 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_PKCS82PKEY 3 ,
 .Xr EVP_PKEY_add1_attr 3 ,
 .Xr EVP_PKEY_asn1_new 3 ,
 .Xr EVP_PKEY_cmp 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 820957dfa9..03f9970097 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.200 2021/10/25 12:25:14 schwarze Exp $
+# $OpenBSD: Makefile,v 1.201 2021/10/25 13:48:12 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -159,6 +159,7 @@ MAN=	\
         EVP_EncodeInit.3 \
         EVP_EncryptInit.3 \
         EVP_OpenInit.3 \
+        EVP_PKCS82PKEY.3 \
         EVP_PKEY_add1_attr.3 \
         EVP_PKEY_asn1_new.3 \
         EVP_PKEY_asn1_get_count.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 639eceeded..2eb9aef054 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.5 2021/10/25 12:25:14 schwarze Exp $
+.\"     $OpenBSD: PKCS8_PRIV_KEY_INFO_new.3,v 1.6 2021/10/25 13:48:12 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -50,6 +50,7 @@ if an error occurs.
 .Sh SEE ALSO
 .Xr d2i_PKCS8_PRIV_KEY_INFO 3 ,
 .Xr d2i_PKCS8PrivateKey_bio 3 ,
+.Xr EVP_PKCS82PKEY 3 ,
 .Xr EVP_PKEY_asn1_set_private 3 ,
 .Xr PEM_read_PKCS8_PRIV_KEY_INFO 3 ,
 .Xr PKCS12_parse 3 ,
diff --git a/src/lib/libcrypto/man/PKCS8_pkey_set0.3 b/src/lib/libcrypto/man/PKCS8_pkey_set0.3
index c7e4fd0ea4..975f3fbebd 100644
--- a/src/lib/libcrypto/man/PKCS8_pkey_set0.3
+++ b/src/lib/libcrypto/man/PKCS8_pkey_set0.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.1 2021/10/25 12:25:14 schwarze Exp $
+.\" $OpenBSD: PKCS8_pkey_set0.3,v 1.2 2021/10/25 13:48:12 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -140,6 +140,7 @@ or
 if no attributes are set.
 .Sh SEE ALSO
 .Xr ASN1_STRING_set0 3 ,
+.Xr EVP_PKCS82PKEY 3 ,
 .Xr OBJ_nid2obj 3 ,
 .Xr PKCS8_PRIV_KEY_INFO_new 3 ,
 .Xr STACK_OF 3 ,