Basic cleanup:

Simplify one-line description.
List each function with the correct header file.
Use the same parameter names as in ASN1_item_d2i(3).
Point to ASN1_item_d2i(3) for details.
Sort the text.
Add some useful cross references.

1 files changed, 102 insertions, 80 deletions

diff --git a/src/lib/libcrypto/man/d2i_RSAPublicKey.3 b/src/lib/libcrypto/man/d2i_RSAPublicKey.3
index 22d904157f..7a65bed7a4 100644
--- a/src/lib/libcrypto/man/d2i_RSAPublicKey.3
+++ b/src/lib/libcrypto/man/d2i_RSAPublicKey.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: d2i_RSAPublicKey.3,v 1.6 2016/12/25 22:15:10 schwarze Exp $
+.\"     $OpenBSD: d2i_RSAPublicKey.3,v 1.7 2016/12/26 16:36:34 schwarze Exp $
 .\"     OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file was written by Ulf Moeller <ulf@openssl.org> and
@@ -50,93 +50,97 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 25 2016 $
+.Dd $Mdocdate: December 26 2016 $
 .Dt D2I_RSAPUBLICKEY 3
 .Os
 .Sh NAME
 .Nm d2i_RSAPublicKey ,
 .Nm i2d_RSAPublicKey ,
+.Nm d2i_RSAPrivateKey ,
+.Nm i2d_RSAPrivateKey ,
+.Nm d2i_Netscape_RSA ,
+.Nm i2d_Netscape_RSA ,
 .Nm d2i_RSA_PUBKEY ,
 .Nm i2d_RSA_PUBKEY ,
 .Nm d2i_RSA_PUBKEY_bio ,
 .Nm d2i_RSA_PUBKEY_fp ,
 .Nm i2d_RSA_PUBKEY_bio ,
-.Nm i2d_RSA_PUBKEY_fp ,
-.Nm d2i_RSAPrivateKey ,
-.Nm i2d_RSAPrivateKey ,
-.Nm i2d_Netscape_RSA ,
-.Nm d2i_Netscape_RSA
-.Nd RSA public and private key encoding functions
+.Nm i2d_RSA_PUBKEY_fp
+.Nd decode and encode RSA keys
 .Sh SYNOPSIS
 .In openssl/rsa.h
-.In openssl/x509.h
 .Ft RSA *
 .Fo d2i_RSAPublicKey
-.Fa "RSA **a"
-.Fa "const unsigned char **pp"
+.Fa "RSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_RSAPublicKey
-.Fa "RSA *a"
-.Fa "unsigned char **pp"
+.Fa "RSA *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft RSA *
+.Fo d2i_RSAPrivateKey
+.Fa "RSA **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_RSAPrivateKey
+.Fa "RSA *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft RSA *
+.Fo d2i_Netscape_RSA
+.Fa "RSA **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fa "int (*cb)()"
+.Fc
+.Ft int
+.Fo i2d_Netscape_RSA
+.Fa "RSA *val_in"
+.Fa "unsigned char **der_out"
+.Fa "int (*cb)()"
 .Fc
+.In openssl/x509.h
 .Ft RSA *
 .Fo d2i_RSA_PUBKEY
-.Fa "RSA **a"
-.Fa "const unsigned char **pp"
+.Fa "RSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_RSA_PUBKEY
-.Fa "RSA *a"
-.Fa "unsigned char **pp"
+.Fa "RSA *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft RSA *
 .Fo d2i_RSA_PUBKEY_bio
-.Fa "BIO *bp"
-.Fa "RSA **a"
+.Fa "BIO *in_bio"
+.Fa "RSA **val_out"
 .Fc
 .Ft RSA *
 .Fo d2i_RSA_PUBKEY_fp
-.Fa "FILE *fp"
-.Fa "RSA **a"
+.Fa "FILE *in_fp"
+.Fa "RSA **val_out"
 .Fc
 .Ft int
 .Fo i2d_RSA_PUBKEY_bio
-.Fa "BIO *bp"
-.Fa "RSA *a"
+.Fa "BIO *out_bio"
+.Fa "RSA *val_in"
 .Fc
 .Ft int
 .Fo i2d_RSA_PUBKEY_fp
-.Fa "FILE *fp"
-.Fa "RSA *a"
-.Fc
-.Ft RSA *
-.Fo d2i_RSAPrivateKey
-.Fa "RSA **a"
-.Fa "const unsigned char **pp"
-.Fa "long length"
-.Fc
-.Ft int
-.Fo i2d_RSAPrivateKey
-.Fa "RSA *a"
-.Fa "unsigned char **pp"
-.Fc
-.Ft int
-.Fo i2d_Netscape_RSA
-.Fa "RSA *a"
-.Fa "unsigned char **pp"
-.Fa "int (*cb)()"
-.Fc
-.Ft RSA *
-.Fo d2i_Netscape_RSA
-.Fa "RSA **a"
-.Fa "const unsigned char **pp"
-.Fa "long length"
-.Fa "int (*cb)()"
+.Fa "FILE *out_fp"
+.Fa "RSA *val_in"
 .Fc
 .Sh DESCRIPTION
+These functions decode and encode RSA private and public keys.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
+.Pp
 .Fn d2i_RSAPublicKey
 and
 .Fn i2d_RSAPublicKey
@@ -144,55 +148,73 @@ decode and encode a PKCS#1
 .Vt RSAPublicKey
 structure.
 .Pp
+.Fn d2i_RSAPrivateKey
+and
+.Fn i2d_RSAPrivateKey
+decode and encode a PKCS#1
+.Vt RSAPrivateKey
+structure.
+The
+.Vt RSA
+structure passed to the private key encoding functions should have
+all the PKCS#1 private key components present.
+The data encoded by the private key functions is unencrypted and
+therefore offers no private key security.
+.Pp
+.Fn d2i_Netscape_RSA
+and
+.Fn i2d_Netscape_RSA
+decode and encode an RSA private key in NET format.
+These functions are present to provide compatibility with
+certain very old software.
+The NET format has some severe security weaknesses and should be
+avoided if possible.
+.Pp
 .Fn d2i_RSA_PUBKEY
 and
 .Fn i2d_RSA_PUBKEY
 decode and encode an RSA public key using an ASN.1
 .Vt SubjectPublicKeyInfo
-(certificate public key) structure.
-.Pp
+structure.
 .Fn d2i_RSA_PUBKEY_bio ,
 .Fn d2i_RSA_PUBKEY_fp ,
 .Fn i2d_RSA_PUBKEY_bio ,
 and
 .Fn i2d_RSA_PUBKEY_fp
-are similar to
-.Fn d2i_RSA_PUBKEY
-and
-.Fn i2d_RSA_PUBKEY
-except that they decode or encode using a
+are similar except that they decode or encode using a
 .Vt BIO
 or
 .Vt FILE
 pointer.
-.Pp
+.Sh RETURN VALUES
+.Fn d2i_RSAPublicKey ,
 .Fn d2i_RSAPrivateKey ,
-.Fn i2d_RSAPrivateKey
-decode and encode a PKCS#1
-.Vt RSAPrivateKey
-structure.
-.Pp
 .Fn d2i_Netscape_RSA ,
-.Fn i2d_Netscape_RSA
-decode and encode an RSA private key in NET format.
-.Pp
-The usage of all of these functions is similar to
-.Xr d2i_X509 3
+.Fn d2i_RSA_PUBKEY ,
+.Fn d2i_RSA_PUBKEY_bio ,
 and
-.Xr i2d_X509 3 .
-.Pp
-The
+.Fn d2i_RSA_PUBKEY_fp
+return a valid
 .Vt RSA
-structure passed to the private key encoding functions should have all
-the PKCS#1 private key components present.
+object or
+.Dv NULL
+if an error occurs.
 .Pp
-The data encoded by the private key functions is unencrypted and
-therefore offers no private key security.
+.Fn i2d_RSAPublicKey ,
+.Fn i2d_RSAPrivateKey ,
+.Fn i2d_Netscape_RSA ,
+and
+.Fn i2d_RSA_PUBKEY
+return the number of bytes successfully encoded or a negative value
+if an error occurs.
 .Pp
-The NET format functions are present to provide compatibility with
-certain very old software.
-This format has some severe security weaknesses and should be avoided if
-possible.
+.Fn i2d_RSA_PUBKEY_bio
+and
+.Fn i2d_RSA_PUBKEY_fp
+return 1 for success or 0 if an error occurs.
 .Sh SEE ALSO
-.Xr d2i_X509 3 ,
-.Xr RSA_new 3
+.Xr ASN1_item_d2i 3 ,
+.Xr EVP_PKEY_set1_RSA 3 ,
+.Xr PEM_write_RSAPrivateKey 3 ,
+.Xr RSA_new 3 ,
+.Xr X509_PUBKEY_new 3