diff options
author | Matt Caswell <matt@openssl.org> | 2015-02-10 16:08:33 +0000 |
---|---|---|
committer | Matt Caswell <matt@openssl.org> | 2015-02-25 17:13:19 +0000 |
commit | 09f278f9252025846dee8aa992ef7079c70b99d0 (patch) | |
tree | 2a84cf3520d2a40d502b42183090f8ed573545dd /doc | |
parent | 93b83d0626e73bb09559ce85aefa418ac7318d59 (diff) |
Add dire warnings about the "reuse" capability of the d2i_* functions.
Reviewed-by: Emilia Käsper <emilia@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/d2i_X509.pod | 18 |
1 files changed, 13 insertions, 5 deletions
diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod index fea6e868e5..03236769a0 100644 --- 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 |