First example of how to fix the d2i_*() manuals:

- add four missing functions found in OpenSSL doc/man3/d2i_X509.pod
- simplify .Nd
- drop needless extra include line
- use the same parameter names as in ASN1_item_d2i(3)
- point to ASN1_item_d2i(3) for details
- sort the text and simplify the wording

More work is needed on STANDARDS references.

1 files changed, 123 insertions, 98 deletions

diff --git a/lib/libcrypto/man/d2i_DSAPublicKey.3 b/lib/libcrypto/man/d2i_DSAPublicKey.3
index 421a6e50538..34681311780 100644
--- a/lib/libcrypto/man/d2i_DSAPublicKey.3
+++ b/lib/libcrypto/man/d2i_DSAPublicKey.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: d2i_DSAPublicKey.3,v 1.6 2016/12/12 13:58:46 schwarze Exp $
+.\"	$OpenBSD: d2i_DSAPublicKey.3,v 1.7 2016/12/24 23:22:52 schwarze Exp $
 .\"	OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 12 2016 $
+.Dd $Mdocdate: December 24 2016 $
 .Dt D2I_DSAPUBLICKEY 3
 .Os
 .Sh NAME
@@ -63,116 +63,162 @@
 .Nm i2d_DSA_PUBKEY_fp ,
 .Nm d2i_DSAPrivateKey ,
 .Nm i2d_DSAPrivateKey ,
+.Nm d2i_DSAPrivateKey_bio ,
+.Nm d2i_DSAPrivateKey_fp ,
+.Nm i2d_DSAPrivateKey_bio ,
+.Nm i2d_DSAPrivateKey_fp ,
 .Nm d2i_DSAparams ,
 .Nm i2d_DSAparams ,
 .Nm DSAparams_dup ,
 .Nm d2i_DSA_SIG ,
 .Nm i2d_DSA_SIG
-.Nd DSA key encoding and parsing functions
+.Nd decode and encode DSA keys
 .Sh SYNOPSIS
 .In openssl/dsa.h
-.In openssl/x509.h
 .Ft DSA *
 .Fo d2i_DSAPublicKey
-.Fa "DSA **a"
-.Fa "const unsigned char **pp"
+.Fa "DSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_DSAPublicKey
-.Fa "const DSA *a"
-.Fa "unsigned char **pp"
+.Fa "const DSA *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft DSA *
 .Fo d2i_DSA_PUBKEY
-.Fa "DSA **a"
-.Fa "const unsigned char **pp"
+.Fa "DSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_DSA_PUBKEY
-.Fa "const DSA *a"
-.Fa "unsigned char **pp"
+.Fa "const DSA *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft DSA *
 .Fo d2i_DSA_PUBKEY_bio
-.Fa "BIO *bp"
-.Fa "DSA **dsa"
+.Fa "BIO *in_bio"
+.Fa "DSA **val_out"
 .Fc
 .Ft DSA *
 .Fo d2i_DSA_PUBKEY_fp
-.Fa "FILE *fp"
-.Fa "DSA *dsa"
+.Fa "FILE *in_fp"
+.Fa "DSA **val_out"
 .Fc
 .Ft int
 .Fo i2d_DSA_PUBKEY_bio
-.Fa "BIO *bp"
-.Fa "DSA *dsa"
+.Fa "BIO *out_bio"
+.Fa "DSA *val_in"
 .Fc
 .Ft int
 .Fo i2d_DSA_PUBKEY_fp
-.Fa "FILE *fp"
-.Fa "DSA *dsa"
+.Fa "FILE *out_fp"
+.Fa "DSA *val_in"
 .Fc
 .Ft DSA *
 .Fo d2i_DSAPrivateKey
-.Fa "DSA **a"
-.Fa "const unsigned char **pp"
+.Fa "DSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_DSAPrivateKey
-.Fa "const DSA *a"
-.Fa "unsigned char **pp"
+.Fa "const DSA *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft DSA *
+.Fo d2i_DSAPrivateKey_bio
+.Fa "BIO *in_bio"
+.Fa "DSA **val_out"
+.Fc
+.Ft DSA *
+.Fo d2i_DSAPrivateKey_fp
+.Fa "FILE *in_fp"
+.Fa "DSA **val_out"
+.Fc
+.Ft int
+.Fo i2d_DSAPrivateKey_bio
+.Fa "BIO *out_bio"
+.Fa "DSA *val_in"
+.Fc
+.Ft int
+.Fo i2d_DSAPrivateKey_fp
+.Fa "FILE *out_fp"
+.Fa "DSA *val_in"
 .Fc
 .Ft DSA *
 .Fo d2i_DSAparams
-.Fa "DSA **a"
-.Fa "const unsigned char **pp"
+.Fa "DSA **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_DSAparams
-.Fa "const DSA *a"
-.Fa "unsigned char **pp"
+.Fa "const DSA *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft DSA *
 .Fo DSAparams_dup
-.Fa "DSA *dsa"
+.Fa "DSA *val_in"
 .Fc
 .Ft DSA_SIG *
 .Fo d2i_DSA_SIG
-.Fa "DSA_SIG **a"
-.Fa "const unsigned char **pp"
+.Fa "DSA_SIG **val_out"
+.Fa "const unsigned char **der_in"
 .Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_DSA_SIG
-.Fa "const DSA_SIG *a"
-.Fa "unsigned char **pp"
+.Fa "const DSA_SIG *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Sh DESCRIPTION
+These functions decode and encode DSA keys and parameters.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
+.Pp
 .Fn d2i_DSAPublicKey
 and
 .Fn i2d_DSAPublicKey
-decode and encode the DSA public key components structure.
+decode and encode the DSA public key components using a non-standard
+format, so consider using
+.Fn d2i_DSA_PUBKEY
+and
+.Fn i2d_DSA_PUBKEY
+instead.
+The actual data encoded depends on the value of
+.Fa val_in->write_params .
+If
+.Fa val_in->write_params
+is zero, only the
+.Fa val_in->pub_key
+field is encoded as an
+.Sy INTEGER .
+If
+.Fa val_in->write_params
+is 1, then a
+.Sy SEQUENCE
+consisting of the
+.Fa val_in->p ,
+.Fa val_in->q ,
+.Fa val_in->g ,
+and
+.Fa val_in->pub_key
+fields is encoded.
 .Pp
 .Fn d2i_DSA_PUBKEY
 and
 .Fn i2d_DSA_PUBKEY
 decode and encode a DSA public key using a SubjectPublicKeyInfo
 (certificate public key) structure.
-.Pp
 .Fn d2i_DSA_PUBKEY_bio ,
 .Fn d2i_DSA_PUBKEY_fp ,
 .Fn i2d_DSA_PUBKEY_bio ,
 and
 .Fn i2d_DSA_PUBKEY_fp
-are similar to
-.Fn d2i_DSA_PUBKEY
-and
-.Fn i2d_DSA_PUBKEY
-except that they decode or encode using a
+are similar except that they decode or encode using a
 .Vt BIO
 or
 .Vt FILE
@@ -182,6 +228,35 @@ pointer.
 and
 .Fn i2d_DSAPrivateKey
 decode and encode the DSA private key components.
+The
+.Vt DSA
+object passed to the private key encoding functions should have all
+the private key components present.
+These functions use a non-standard structure consisting of a
+SEQUENCE containing the
+.Fa val_in->p ,
+.Fa val_in->q ,
+.Fa val_in->g ,
+.Fa val_in->pub_key ,
+and
+.Fa val_in->priv_key
+fields.
+This data format is unencrypted.
+For private key security when writing private keys to files,
+consider using
+.Xr PEM_write_DSAPrivateKey 3
+instead.
+The
+.Fn d2i_DSAPrivateKey_bio ,
+.Fn d2i_DSAPrivateKey_fp ,
+.Fn i2d_DSAPrivateKey_bio ,
+and
+.Fn i2d_DSAPrivateKey_fp
+are similar except that they decode or encode using a
+.Vt BIO
+or
+.Vt FILE
+pointer.
 .Pp
 .Fn d2i_DSAparams
 and
@@ -203,81 +278,31 @@ and
 decode and encode a DSA signature using a
 .Sy Dss-Sig-Value
 structure as defined in RFC 2459.
-.Pp
-The usage of all of these functions is similar to
-.Xr d2i_X509 3
-and
-.Xr i2d_X509 3 .
-.Pp
-The
-.Vt DSA
-structure passed to the private key encoding functions should have all
-the private key components present.
-.Pp
-The data encoded by the private key functions is unencrypted and
-therefore offers no private key security.
-.Pp
-The
-.Fn *_DSA_PUBKEY
-functions should be used in preference to the
-.Fn *_DSAPublicKey
-functions when encoding public keys because they use a standard format.
-.Pp
-The
-.Fn *_DSAPublicKey
-functions use a non-standard format.
-The actual data encoded depends on the value of
-.Fa a->write_params .
-If
-.Fa a->write_params
-is zero, then only the
-.Fa a->pub_key
-field is encoded as an
-.Sy INTEGER .
-If
-.Fa a->write_params
-is 1, then a
-.Sy SEQUENCE
-consisting of the
-.Fa a->p ,
-.Fa a->q ,
-.Fa a->g ,
-and
-.Fa a->pub_key
-fields is encoded.
-.Pp
-The
-.Fn *_DSAPrivateKey
-functions also use a non-standard structure consisting of a
-SEQUENCE containing the
-.Fa a->p ,
-.Fa a->q ,
-.Fa a->g ,
-.Fa a->pub_key ,
-and
-.Fa a->priv_key
-fields.
 .Sh RETURN VALUES
 .Fn d2i_DSAPublicKey ,
 .Fn d2i_DSA_PUBKEY ,
 .Fn d2i_DSA_PUBKEY_bio ,
 .Fn d2i_DSA_PUBKEY_fp ,
 .Fn d2i_DSAPrivateKey ,
+.Fn d2i_DSAPrivateKey_bio ,
+.Fn d2i_DSAPrivateKey_fp ,
 .Fn d2i_DSAparams ,
 and
 .Fn DSAparams_dup
 return a valid
 .Vt DSA
-structure or
+object or
 .Dv NULL
 if an error occurs.
 .Pp
 .Fn d2i_DSA_SIG
 returns a valid
 .Vt DSA_SIG
-structure or
+object or
 .Dv NULL
 if an error occurs.
 .Sh SEE ALSO
-.Xr d2i_X509 3 ,
-.Xr DSA_new 3
+.Xr ASN1_item_d2i 3 ,
+.Xr DSA_new 3 ,
+.Xr DSA_SIG_new 3 ,
+.Xr PEM_write_DSAPrivateKey 3