Add dire warnings about the "reuse" capability of the d2i_* functions.

Reviewed-by: Emilia Käsper <emilia@openssl.org>

diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod
index fea6e868e5c01316d5d85cca1c77f57697280f00..03236769a0637e2ed339d5d7a83a6c961bdbea0d 100644 (file)
--- a/doc/crypto/d2i_X509.pod
+++ b/doc/crypto/d2i_X509.pod
@@ -30,8 +30,11 @@ 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>
 then it is assumed that B<*px> contains a valid B<X509>
-structure and an attempt is made to reuse it. If the call is
-successful B<*in> is incremented to the byte following the
+structure and an attempt is made to reuse it. This "reuse" capability is present
+for historical compatibility but its use is B<strongly discouraged> (see BUGS
+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.
 
 i2d_X509() encodes the structure pointed to by B<x> into DER format.
@@ -87,7 +90,8 @@ 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
+usage of ASN1 functions: after one structure is encoded or decoded    if (a != NULL)
+        (*a) = ret;
 another will processed after it.
 
 =head1 EXAMPLES
@@ -209,7 +213,8 @@ 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
+then the encoded structure may contain invalid data or omit the    if (a != NULL)
+        (*a) = ret;
 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.
@@ -233,7 +238,10 @@ i2d_re_X509_tbs().
 
 d2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure
 or B<NULL> if an error occurs. The error code that can be obtained by
-L<ERR_get_error(3)|ERR_get_error(3)>. 
+L<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used
+with a valid X509 structure being passed in via B<px> then the object is not
+freed in the event of error but may be in a potentially invalid or inconsistent
+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