From 7d940d3cb44118fc6856a485301420ece0bb0a25 Mon Sep 17 00:00:00 2001 From: schwarze Date: Mon, 25 Oct 2021 13:48:12 +0000 Subject: [PATCH] new manual page EVP_PKCS82PKEY(3), also documenting EVP_PKEY2PKCS8(3) --- lib/libcrypto/man/EVP_PKCS82PKEY.3 | 63 +++++++++++++++++++++ lib/libcrypto/man/EVP_PKEY_asn1_new.3 | 10 ++-- lib/libcrypto/man/EVP_PKEY_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 | 3 +- lib/libcrypto/man/PKCS8_pkey_set0.3 | 3 +- 6 files changed, 77 insertions(+), 10 deletions(-) create mode 100644 lib/libcrypto/man/EVP_PKCS82PKEY.3 diff --git a/lib/libcrypto/man/EVP_PKCS82PKEY.3 b/lib/libcrypto/man/EVP_PKCS82PKEY.3 new file mode 100644 index 00000000000..5fed846fe6a --- /dev/null +++ b/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 +.\" +.\" 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/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/lib/libcrypto/man/EVP_PKEY_asn1_new.3 index 5d915d01834..a363a9615f5 100644 --- a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 +++ b/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/lib/libcrypto/man/EVP_PKEY_new.3 b/lib/libcrypto/man/EVP_PKEY_new.3 index 754fe94e608..5850c63d25f 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.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/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile index 820957dfa95..03f99700979 100644 --- a/lib/libcrypto/man/Makefile +++ b/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 @@ -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/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 b/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 index 639eceededc..2eb9aef0540 100644 --- a/lib/libcrypto/man/PKCS8_PRIV_KEY_INFO_new.3 +++ b/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 .\" @@ -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/lib/libcrypto/man/PKCS8_pkey_set0.3 b/lib/libcrypto/man/PKCS8_pkey_set0.3 index c7e4fd0ea4a..975f3fbebd4 100644 --- a/lib/libcrypto/man/PKCS8_pkey_set0.3 +++ b/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 .\" @@ -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 , -- 2.20.1