cherry pick pr-512 changes

[openssl.git] / doc / crypto / d2i_X509.pod

diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 3cd2509d8b04ac98dc04dcad6bfb0a456e1a482c..422edfcf83b273474747bed5f9fe31360851f65d 100644 (file)
--- a/doc/crypto/d2i_X509.pod
+++ b/doc/crypto/d2i_X509.pod
@@ -9,8 +9,10 @@ i2d_X509_fp - X509 encode and decode functions
 
  #include <openssl/x509.h>
 
- X509 *d2i_X509(X509 **px, const unsigned char **in, int len);
+ X509 *d2i_X509(X509 **px, const unsigned char **in, long len);
+ X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len);
  int i2d_X509(X509 *x, unsigned char **out);
+ int i2d_X509_AUX(X509 *x, unsigned char **out);
 
  X509 *d2i_X509_bio(BIO *bp, X509 **x);
  X509 *d2i_X509_fp(FILE *fp, X509 **x);
@@ -25,7 +27,7 @@ i2d_X509_fp - X509 encode and decode functions
 The X509 encode and decode routines encode and parse an
 B<X509> structure, which represents an X509 certificate.
 
-d2i_X509() attempts to decode B<len> bytes at B<*in>. If 
+d2i_X509() attempts to decode B<len> bytes at B<*in>. If
 successful a pointer to the B<X509> structure is returned. If an error
 occurred then B<NULL> is returned. If B<px> is not B<NULL> then the
 returned structure is written to B<*px>. If B<*px> is not B<NULL>
@@ -37,17 +39,27 @@ below, and the discussion in the RETURN VALUES section).
 If the call is successful B<*in> is incremented to the byte following the
 parsed data.
 
+d2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of
+an X509 certificate followed 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.
+
 i2d_X509() encodes the structure pointed to by B<x> into DER format.
 If B<out> is not B<NULL> is writes the DER encoded data to the buffer
 at B<*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. 
+returns the length of the encoded data.
 
 If B<*out> is B<NULL> memory will be
 allocated for a buffer and the encoded data written to it. In this
 case B<*out> is not incremented and it points to the start of the
 data just written.
 
+i2d_X509_AUX() is similar to i2d_X509(), 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, this is a non-standard OpenSSL-specific data format.
+
 d2i_X509_bio() is similar to d2i_X509() except it attempts
 to parse data from BIO B<bp>.
 
@@ -103,7 +115,7 @@ Allocate and encode the DER encoding of an X509 structure:
  buf = NULL;
  len = i2d_X509(x, &buf);
  if (len < 0)
-       /* error */
+        /* error */
 
 Attempt to decode a buffer:
 
@@ -143,7 +155,7 @@ mistake is to attempt to use a buffer directly as follows:
  len = i2d_X509(x, NULL);
  buf = OPENSSL_malloc(len);
  if (buf == NULL)
-       /* error */
+        /* error */
 
  i2d_X509(x, &buf);
  /* Other stuff ... */
@@ -159,7 +171,7 @@ Another trap to avoid is misuse of the B<xp> argument to d2i_X509():
  X509 *x;
 
  if (!d2i_X509(&x, &p, len))
-       /* Some error */
+        /* Some error */
 
 This will probably crash somewhere in d2i_X509(). The reason for this
 is that the variable B<x> is uninitialized and an attempt will be made to
@@ -169,7 +181,7 @@ happen.
 
 =head1 BUGS
 
-In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when 
+In some versions of OpenSSL the "reuse" behaviour of d2i_X509() when
 B<*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.
@@ -207,10 +219,10 @@ state.
 
 i2d_X509() returns the number of bytes successfully encoded or a negative
 value if an error occurs. The error code can be obtained by
-L<ERR_get_error(3)>. 
+L<ERR_get_error(3)>.
 
-i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error 
-occurs The error code can be obtained by L<ERR_get_error(3)>. 
+i2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error
+occurs The error code can be obtained by L<ERR_get_error(3)>.
 
 =head1 SEE ALSO
 
@@ -231,4 +243,13 @@ L<X509_sign(3)>,
 L<X509V3_get_d2i(3)>,
 L<X509_verify_cert(3)>
 
+=head1 COPYRIGHT
+
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
 =cut