Basic cleanup:

Improve .Nd.
Sort functions.
Use the same parameter names as in ASN1_item_d2i(3).
Point to ASN1_item_d2i(3) for all he details.
Delete all the information that's now in ASN1_item_d2i(3).
Add missing entries to the RETURN VALUES section.
Add STANDARDS section.

1 files changed, 60 insertions, 311 deletions

diff --git a/lib/libcrypto/man/d2i_X509.3 b/lib/libcrypto/man/d2i_X509.3
index 7ca3abf2d96..1b716d2fbbd 100644
--- a/lib/libcrypto/man/d2i_X509.3
+++ b/lib/libcrypto/man/d2i_X509.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: d2i_X509.3,v 1.4 2016/12/08 20:22:08 jmc Exp $
+.\"	$OpenBSD: d2i_X509.3,v 1.5 2016/12/28 03:35:32 schwarze Exp $
 .\"	OpenSSL 94480b57 Sep 12 23:34:41 2009 +0000
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -49,103 +49,86 @@
 .\" 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 28 2016 $
 .Dt D2I_X509 3
 .Os
 .Sh NAME
 .Nm d2i_X509 ,
-.Nm d2i_X509_AUX ,
 .Nm i2d_X509 ,
-.Nm i2d_X509_AUX ,
 .Nm d2i_X509_bio ,
 .Nm d2i_X509_fp ,
 .Nm i2d_X509_bio ,
-.Nm i2d_X509_fp
-.Nd X509 encode and decode functions
+.Nm i2d_X509_fp ,
+.Nm d2i_X509_AUX ,
+.Nm i2d_X509_AUX
+.Nd decode and encode X.509 certificates
 .Sh SYNOPSIS
 .In openssl/x509.h
 .Ft X509 *
 .Fo d2i_X509
-.Fa "X509 **px"
-.Fa "const unsigned char **in"
-.Fa "long len"
-.Fc
-.Ft X509 *
-.Fo d2i_X509_AUX
-.Fa "X509 **px"
-.Fa "const unsigned char **in"
-.Fa "long len"
+.Fa "X509 **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
 .Fc
 .Ft int
 .Fo i2d_X509
-.Fa "X509 *x"
-.Fa "unsigned char **out"
-.Fc
-.Ft int
-.Fo i2d_X509_AUX
-.Fa "X509 *x"
-.Fa "unsigned char **out"
+.Fa "X509 *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Ft X509 *
 .Fo d2i_X509_bio
-.Fa "BIO *bp"
-.Fa "X509 **x"
+.Fa "BIO *in_bio"
+.Fa "X509 **val_out"
 .Fc
 .Ft X509 *
 .Fo d2i_X509_fp
-.Fa "FILE *fp"
-.Fa "X509 **x"
+.Fa "FILE *in_fp"
+.Fa "X509 **val_out"
 .Fc
 .Ft int
 .Fo i2d_X509_bio
-.Fa "BIO *bp"
-.Fa "X509 *x"
+.Fa "BIO *out_bio"
+.Fa "X509 *val_in"
 .Fc
 .Ft int
 .Fo i2d_X509_fp
-.Fa "FILE *fp"
-.Fa "X509 *x"
+.Fa "FILE *out_fp"
+.Fa "X509 *val_in"
+.Fc
+.Ft X509 *
+.Fo d2i_X509_AUX
+.Fa "X509 **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_X509_AUX
+.Fa "X509 *val_in"
+.Fa "unsigned char **der_out"
 .Fc
 .Sh DESCRIPTION
-The X509 encode and decode routines encode and parse an
-.Vt X509
-structure, which represents an X509 certificate.
+These functions decode and encode X.509 certificates
+and some of their substructures.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
 .Pp
 .Fn d2i_X509
-attempts to decode
-.Fa len
-bytes at
-.Pf * Fa in .
-If successful, a pointer to the
-.Vt X509
-structure is returned.
-If an error occurred,
-.Dv NULL
-is returned.
-If
-.Fa px
-is not
-.Dv NULL ,
-the returned structure is written to
-.Pf * Fa px .
-If
-.Pf * Fa px
-is not
-.Dv NULL ,
-then it is assumed that
-.Pf * Fa px
-contains a valid
-.Vt X509
-structure and an attempt is made to reuse it.
-This "reuse" capability is present for historical compatibility,
-but its use is strongly discouraged; see the
-.Sx BUGS
 and
-.Sx RETURN VALUES
-sections.
-If the call is successful,
-.Pf * Fa in
-is incremented to the byte following the parsed data.
+.Fn i2d_X509
+decode and encode an ASN.1
+.Vt Certificate
+structure defined in RFC 5280 section 4.1.
+.Pp
+.Fn d2i_X509_bio ,
+.Fn d2i_X509_fp ,
+.Fn i2d_X509_bio ,
+and
+.Fn i2d_X509_fp
+are similar except that they decode or encode using a
+.Vt BIO
+or
+.Vt FILE
+pointer.
 .Pp
 .Fn d2i_X509_AUX
 is similar to
@@ -155,29 +138,6 @@ by auxiliary trust information.
 This is used by the PEM routines to read TRUSTED CERTIFICATE objects.
 This function should not be called on untrusted input.
 .Pp
-.Fn i2d_X509
-encodes the structure pointed to by
-.Fa x
-into DER format.
-If
-.Fa out
-is not
-.Dv NULL ,
-it writes the DER encoded data to the buffer at
-.Pf * Fa out
-and increments it to point after the data just written.
-If the return value is negative an error occurred, otherwise it returns
-the length of the encoded data.
-.Pp
-For OpenSSL 0.9.7 and later if
-.Pf * Fa out
-is
-.Dv NULL ,
-memory will be allocated for a buffer and the encoded data written to it.
-In this case
-.Pf * Fa out
-is not incremented and it points to the start of the data just written.
-.Pp
 .Fn i2d_X509_AUX
 is similar to
 .Fn i2d_X509 ,
@@ -185,94 +145,12 @@ but the encoded output contains both the certificate and any auxiliary
 trust information.
 This is used by the PEM routines to write TRUSTED CERTIFICATE objects.
 Note that this is a non-standard OpenSSL-specific data format.
-.Pp
-.Fn d2i_X509_bio
-is similar to
-.Fn d2i_X509
-except it attempts to parse data from
-.Vt BIO
-.Fa bp .
-.Pp
-.Fn d2i_X509_fp
-is similar to
-.Fn d2i_X509
-except it attempts to parse data from the
-.Vt FILE
-pointer
-.Fa fp .
-.Pp
-.Fn i2d_X509_bio
-is similar to
-.Fn i2d_X509
-except it writes the encoding of the structure
-.Fa x
-to
-.Vt BIO
-.Fa bp
-and it returns 1 for success or 0 for failure.
-.Pp
-.Fn i2d_X509_fp
-is similar to
-.Fn i2d_X509
-except it writes the encoding of the structure
-.Fa x
-to
-.Vt BIO
-.Fa bp
-and it returns 1 for success or 0 for failure.
-.Pp
-The letters
-.Sy i
-and
-.Sy d
-in, for example,
-.Fn i2d_X509
-stand for "internal" (that is an internal C structure) and "DER",
-so that
-.Fn i2d_X509
-converts from internal to DER.
-.Pp
-The functions can also understand BER forms.
-.Pp
-The actual
-.Vt X509
-structure passed to
-.Fn i2d_X509
-must be a valid populated
-.Vt X509
-structure.
-It cannot simply be fed with an empty structure such as that returned by
-.Xr X509_new 3 .
-.Pp
-The encoded data is in binary form and may contain embedded zeroes.
-Therefore any
-.Vt FILE
-pointers or
-.Vt BIO Ns s
-should be opened in binary mode.
-Functions such as
-.Xr strlen 3
-will
-.Sy not
-return the correct length of the encoded structure.
-.Pp
-The ways that
-.Pf * Fa in
-and
-.Pf * Fa out
-are incremented after the operation can trap the unwary.
-See the
-.Sx CAVEATS
-section for some common errors.
-.Pp
-The reason for the auto increment behaviour is to reflect a typical
-usage of ASN.1 functions: after one structure is encoded or decoded,
-another will be processed after it.
 .Sh RETURN VALUES
 .Fn d2i_X509 ,
 .Fn d2i_X509_bio ,
+.Fn d2i_X509_fp ,
 and
-.Fn d2i_X509_fp
+.Fn d2i_X509_AUX
 return a valid
 .Vt X509
 structure or
@@ -280,8 +158,10 @@ structure or
 if an error occurs.
 .Pp
 .Fn i2d_X509
-returns the number of bytes successfully encoded or a negative value if
-an error occurs.
+and
+.Fn i2d_X509_AUX
+return the number of bytes successfully encoded or a negative value
+if an error occurs.
 .Pp
 .Fn i2d_X509_bio
 and
@@ -290,64 +170,12 @@ return 1 for success or 0 if an error occurs.
 .Pp
 For all functions, the error code can be obtained by
 .Xr ERR_get_error 3 .
-If the "reuse" capability has been used with a valid
-.Vt X509
-structure being passed in via
-.Fa px ,
-then the object is not freed in the event of an error, but may be
-in a potentially invalid or inconsistent state.
-.Sh EXAMPLES
-Allocate and encode the DER encoding of an X509 structure:
-.Bd -literal -offset indent
-int len;
-unsigned char *buf, *p;
-
-len = i2d_X509(x, NULL);
-buf = malloc(len);
-if (buf == NULL)
-	/* error */
-p = buf;
-i2d_X509(x, &p);
-.Ed
-.Pp
-Using OpenSSL 0.9.7 or later this can be simplified to:
-.Bd -literal -offset indent
-int len;
-unsigned char *buf;
-
-buf = NULL;
-len = i2d_X509(x, &buf);
-if (len < 0)
-	/* error */
-.Ed
-.Pp
-Attempt to decode a buffer:
-.Bd -literal -offset indent
-X509 *x;
-unsigned char *buf, *p;
-int len;
-
-/* Something to setup buf and len */
-p = buf;
-x = d2i_X509(NULL, &p, len);
-if (x == NULL)
-    /* Some error */
-.Ed
-.Pp
-Alternative technique:
-.Bd -literal -offset indent
-X509 *x;
-unsigned char *buf, *p;
-int len;
-
-/* Something to setup buf and len */
-p = buf;
-x = NULL;
-if(!d2i_X509(&x, &p, len))
-    /* Some error */
-.Ed
 .Sh SEE ALSO
-.Xr ERR_get_error 3
+.Xr ASN1_item_d2i 3 ,
+.Xr X509_new 3
+.Sh STANDARDS
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile
 .Sh HISTORY
 .Fn d2i_X509 ,
 .Fn i2d_X509 ,
@@ -357,82 +185,3 @@ if(!d2i_X509(&x, &p, len))
 and
 .Fn i2d_X509_fp
 are available in all versions of SSLeay and OpenSSL.
-.Sh CAVEATS
-The use of a temporary variable is mandatory.
-A common mistake is to attempt to use a buffer directly as follows:
-.Bd -literal -offset indent
-int len;
-unsigned char *buf;
-
-len = i2d_X509(x, NULL);
-buf = malloc(len);
-if (buf == NULL)
-	/* error */
-i2d_X509(x, &buf);
-/* Other stuff ... */
-free(buf);
-.Ed
-.Pp
-This code will result in
-.Fa buf
-apparently containing garbage because it was incremented after the
-call to point after the data just written.
-Also
-.Fa buf
-will no longer contain the pointer allocated by
-.Xr malloc 3
-and the subsequent call to
-.Xr free 3
-may well crash.
-.Pp
-The auto allocation feature (setting
-.Fa buf
-to
-.Dv NULL )
-only works on OpenSSL 0.9.7 and later.
-Attempts to use it on earlier versions will typically cause a
-segmentation violation.
-.Pp
-Another trap to avoid is misuse of the
-.Fa px
-argument to
-.Sy d2i_X509() :
-.Bd -literal -offset indent
-X509 *x;
-
-if (!d2i_X509(&x, &p, len))
-	/* Some error */
-.Ed
-.Pp
-This will probably crash somewhere in
-.Fn d2i_X509 .
-The reason for this is that the variable
-.Fa x
-is uninitialized and an attempt will be made to interpret its (invalid)
-value as an
-.Vt X509
-structure, typically causing a segmentation violation.
-If
-.Fa x
-is set to
-.Dv NULL
-first then this will not happen.
-.Sh BUGS
-In some versions of OpenSSL the "reuse" behaviour of
-.Fn d2i_X509
-when
-.Pf * Fa px
-is valid is broken and some parts of the reused structure may persist
-if they are not present in the new one.
-As a result the use of this "reuse" behaviour is strongly discouraged.
-.Pp
-In many versions of OpenSSL,
-.Fn i2d_X509
-will not return an error if mandatory fields are not initialized
-due to a programming error.
-Then the encoded structure may contain invalid data or omit the
-fields entirely and will not be parsed by
-.Fn d2i_X509 .
-This may be fixed in future so code should not assume that
-.Fn i2d_X509
-will always succeed.