From 5667f2b73d8867280a0e2b3dd1d8068478634723 Mon Sep 17 00:00:00 2001 From: schwarze <> Date: Sun, 25 Dec 2016 20:01:48 +0000 Subject: Add missing functions d2i_PublicKey(3) and i2d_PublicKey(3) found in OpenSSL doc/man3/d2i_X509.pod. Simplify one-line description. Use the same parameter names as in ASN1_item_d2i(3). Point to ASN1_item_d2i(3) for details. Add a STANDRADS reference regarding PKCS#8 PrivateKeyInfo. Mention d2i_PrivateKey_bio(3) and d2i_PrivateKey_fp(3) in the DESCRIPTION and below RETURN VALUES. Add some missing markup and tweak some wording. Add some cross references. --- src/lib/libcrypto/man/d2i_PrivateKey.3 | 148 +++++++++++++++++++++++++-------- 1 file changed, 113 insertions(+), 35 deletions(-) (limited to 'src/lib') diff --git a/src/lib/libcrypto/man/d2i_PrivateKey.3 b/src/lib/libcrypto/man/d2i_PrivateKey.3 index 10eb5ebeeb..3c5e9f8cc8 100644 --- a/src/lib/libcrypto/man/d2i_PrivateKey.3 +++ b/src/lib/libcrypto/man/d2i_PrivateKey.3 @@ -1,7 +1,24 @@ -.\" $OpenBSD: d2i_PrivateKey.3,v 1.3 2016/12/08 20:22:08 jmc Exp $ +.\" $OpenBSD: d2i_PrivateKey.3,v 1.4 2016/12/25 20:01:48 schwarze Exp $ .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2016 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. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" Copyright (c) 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -48,7 +65,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: December 8 2016 $ +.Dd $Mdocdate: December 25 2016 $ .Dt D2I_PRIVATEKEY 3 .Os .Sh NAME @@ -56,44 +73,64 @@ .Nm d2i_AutoPrivateKey , .Nm i2d_PrivateKey , .Nm d2i_PrivateKey_bio , -.Nm d2i_PrivateKey_fp -.Nd decode and encode functions for reading and saving EVP_PKEY structures +.Nm d2i_PrivateKey_fp , +.Nm d2i_PublicKey , +.Nm i2d_PublicKey +.Nd decode and encode EVP_PKEY objects .Sh SYNOPSIS .In openssl/evp.h .Ft EVP_PKEY * .Fo d2i_PrivateKey .Fa "int type" -.Fa "EVP_PKEY **a" -.Fa "const unsigned char **pp" +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **des_in" .Fa "long length" .Fc .Ft EVP_PKEY * .Fo d2i_AutoPrivateKey -.Fa "EVP_PKEY **a" -.Fa "const unsigned char **pp" +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **des_in" .Fa "long length" .Fc .Ft int .Fo i2d_PrivateKey -.Fa "EVP_PKEY *a" -.Fa "unsigned char **pp" +.Fa "EVP_PKEY *val_in" +.Fa "unsigned char **des_out" .Fc .Ft EVP_PKEY * .Fo d2i_PrivateKey_bio -.Fa "BIO *bp" -.Fa "EVP_PKEY **a" +.Fa "BIO *in_bio" +.Fa "EVP_PKEY **val_out" .Fc .Ft EVP_PKEY * .Fo d2i_PrivateKey_fp -.Fa "FILE *fp" -.Fa "EVP_PKEY **a" +.Fa "FILE *in_fp" +.Fa "EVP_PKEY **val_out" +.Fc +.Ft EVP_PKEY * +.Fo d2i_PublicKey +.Fa "int type" +.Fa "EVP_PKEY **val_out" +.Fa "const unsigned char **des_in" +.Fa "long length" +.Fc +.Ft int +.Fo i2d_PublicKey +.Fa "EVP_PKEY *val_in" +.Fa "unsigned char **des_out" .Fc .Sh DESCRIPTION +These are algorithm-independent interfaces to decode and encode +private and public keys. +For details about the semantics, examples, caveats, and bugs, see +.Xr ASN1_item_d2i 3 . +.Pp .Fn d2i_PrivateKey decodes a private key using algorithm .Fa type . -It attempts to use any key specific format or PKCS#8 unencrypted -PrivateKeyInfo format. +It attempts to use any key specific format or the PKCS#8 unencrypted +.Vt PrivateKeyInfo +format defined in RFC 5208 section 5. The .Fa type parameter should be a public key algorithm constant such as @@ -104,18 +141,26 @@ An error occurs if the decoded key does not match .Fn d2i_AutoPrivateKey is similar to .Fn d2i_PrivateKey -except that it attempts to automatically detect the private key format. +except that it attempts to automatically detect the algorithm. +.Pp +.Fn d2i_PrivateKey_bio +and +.Fn d2i_PrivateKey_fp +are similar to +.Fn d2i_PrivateKey +except that they read from a +.Vt BIO +or +.Vt FILE +pointer. .Pp .Fn i2d_PrivateKey encodes -.Fa a . +.Fa val_in . It uses a key specific format or, if none is defined for that key type, -PKCS#8 unencrypted PrivateKeyInfo format. -.Pp -These functions are similar to the -.Xr d2i_X509 3 -functions; see -.Xr d2i_X509 3 . +the PKCS#8 unencrypted +.Vt PrivateKeyInfo +format. .Pp All these functions use DER format and unencrypted keys. Applications wishing to encrypt or decrypt private keys should use other @@ -124,31 +169,64 @@ functions such as instead. .Pp If -.Pf * Fa a -is not NULL when calling +.Pf * Fa val_out +is not +.Dv NULL +when calling .Fn d2i_PrivateKey or .Fn d2i_AutoPrivateKey (i.e. an existing structure is being reused) and the key format is PKCS#8, then -.Pf * Fa a +.Pf * Fa val_out will be freed and replaced on a successful call. +.Pp +.Fn d2i_PublicKey +calls +.Xr d2i_DSAPublicKey 3 , +.Xr o2i_ECPublicKey 3 , +or +.Xr d2i_RSAPublicKey 3 +depending on +.Fa type +and stores the result in the returned +.Vt EVP_PKEY +object. +.Pp +.Fn i2d_PublicKey +calls +.Xr i2d_DSAPublicKey 3 , +.Xr i2o_ECPublicKey 3 , +or +.Xr i2d_RSAPublicKey 3 +depending on the algorithm used by +.Fa val_in . .Sh RETURN VALUES -.Fn d2i_PrivateKey +.Fn d2i_PrivateKey , +.Fn d2i_AutoPrivateKey , +.Fn d2i_PrivateKey_bio , +.Fn d2i_PrivateKey_fp , and -.Fn d2i_AutoPrivateKey +.Fn d2i_PublicKey return a valid .Vt EVP_KEY structure or .Dv NULL if an error occurs. -The error code can be obtained by calling -.Xr ERR_get_error 3 . .Pp .Fn i2d_PrivateKey -returns the number of bytes successfully encoded or a negative value if +and +.Fn i2d_PublicKey +return the number of bytes successfully encoded or a negative value if an error occurs. -The error code can be obtained by calling +.Pp +For all functions, the error code can be obtained by calling .Xr ERR_get_error 3 . .Sh SEE ALSO -.Xr d2i_PKCS8PrivateKey_bio 3 +.Xr d2i_PKCS8PrivateKey_bio 3 , +.Xr EVP_PKEY_type 3 , +.Xr PEM_write_PrivateKey 3 , +.Xr PKCS8_PRIV_KEY_INFO_new 3 +.Sh STANDARDS +RFC 5208: Public-Key Cryptography Standards (PKCS) #8: Private-Key +Information Syntax Specification -- cgit v1.2.3-55-g6feb