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.

1 files changed, 113 insertions, 35 deletions

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 <steve@openssl.org>.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2016 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.
+.\"
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
 .\" 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