Clarify negative return from X509_verify_cert()

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

diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index 03236769a0637e2ed339d5d7a83a6c961bdbea0d..2743bc73e70ef578c49a0d2d8dddd45e3bf45e2f 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);
@@ -37,6 +39,11 @@ 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.
@@ -48,6 +55,11 @@ 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>.
 
@@ -90,8 +102,7 @@ can trap the unwary. See the B<WARNINGS> section for some common
 errors.
 
 The reason for the auto increment behaviour is to reflect a typical
-usage of ASN1 functions: after one structure is encoded or decoded    if (a != NULL)
-        (*a) = ret;
+usage of ASN1 functions: after one structure is encoded or decoded
 another will processed after it.
 
 =head1 EXAMPLES
@@ -213,8 +224,7 @@ of this "reuse" behaviour is strongly discouraged.
 
 i2d_X509() will not return an error in many versions of OpenSSL,
 if mandatory fields are not initialized due to a programming error
-then the encoded structure may contain invalid data or omit the    if (a != NULL)
-        (*a) = ret;
+then the encoded structure may contain invalid data or omit the
 fields entirely and will not be parsed by d2i_X509(). This may be
 fixed in future so code should not assume that i2d_X509() will
 always succeed.