diff options
Diffstat (limited to 'doc/crypto/d2i_X509.pod')
| -rw-r--r-- | doc/crypto/d2i_X509.pod | 272 |
1 files changed, 0 insertions, 272 deletions
diff --git a/doc/crypto/d2i_X509.pod b/doc/crypto/d2i_X509.pod deleted file mode 100644 index 2743bc73e70e..000000000000 --- a/doc/crypto/d2i_X509.pod +++ /dev/null @@ -1,272 +0,0 @@ -=pod - -=head1 NAME - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, -i2d_X509_fp - X509 encode and decode functions - -=head1 SYNOPSIS - - #include <openssl/x509.h> - - 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); - - int i2d_X509_bio(BIO *bp, X509 *x); - int i2d_X509_fp(FILE *fp, X509 *x); - - int i2d_re_X509_tbs(X509 *x, unsigned char **out); - -=head1 DESCRIPTION - -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 -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. 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. - -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. - -For OpenSSL 0.9.7 and later 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>. - -d2i_X509_fp() is similar to d2i_X509() except it attempts -to parse data from FILE pointer B<fp>. - -i2d_X509_bio() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_X509_fp() is similar to i2d_X509() except it writes -the encoding of the structure B<x> to BIO B<bp> and it -returns 1 for success and 0 for failure. - -i2d_re_X509_tbs() is similar to i2d_X509() except it encodes -only the TBSCertificate portion of the certificate. - -=head1 NOTES - -The letters B<i> and B<d> in for example B<i2d_X509> stand for -"internal" (that is an internal C structure) and "DER". So -B<i2d_X509> converts from internal to DER. The "re" in -B<i2d_re_X509_tbs> stands for "re-encode", and ensures that a fresh -encoding is generated in case the object has been modified after -creation (see the BUGS section). - -The functions can also understand B<BER> forms. - -The actual X509 structure passed to i2d_X509() must be a valid -populated B<X509> structure it can B<not> simply be fed with an -empty structure such as that returned by X509_new(). - -The encoded data is in binary form and may contain embedded zeroes. -Therefore any FILE pointers or BIOs should be opened in binary mode. -Functions such as B<strlen()> will B<not> return the correct length -of the encoded structure. - -The ways that B<*in> and B<*out> are incremented after the operation -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 -another will processed after it. - -=head1 EXAMPLES - -Allocate and encode the DER encoding of an X509 structure: - - int len; - unsigned char *buf, *p; - - len = i2d_X509(x, NULL); - - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - - p = buf; - - i2d_X509(x, &p); - -If you are using OpenSSL 0.9.7 or later then this can be -simplified to: - - - int len; - unsigned char *buf; - - buf = NULL; - - len = i2d_X509(x, &buf); - - if (len < 0) - /* error */ - -Attempt to decode a buffer: - - 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 */ - -Alternative technique: - - 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 */ - - -=head1 WARNINGS - -The use of temporary variable is mandatory. A common -mistake is to attempt to use a buffer directly as follows: - - int len; - unsigned char *buf; - - len = i2d_X509(x, NULL); - - buf = OPENSSL_malloc(len); - - if (buf == NULL) - /* error */ - - i2d_X509(x, &buf); - - /* Other stuff ... */ - - OPENSSL_free(buf); - -This code will result in B<buf> apparently containing garbage because -it was incremented after the call to point after the data just written. -Also B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()> -and the subsequent call to B<OPENSSL_free()> may well crash. - -The auto allocation feature (setting buf to NULL) only works on OpenSSL -0.9.7 and later. Attempts to use it on earlier versions will typically -cause a segmentation violation. - -Another trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: - - X509 *x; - - if (!d2i_X509(&x, &p, len)) - /* Some error */ - -This will probably crash somewhere in B<d2i_X509()>. The reason for this -is that the variable B<x> is uninitialized and an attempt will be made to -interpret its (invalid) value as an B<X509> structure, typically causing -a segmentation violation. If B<x> is set to NULL first then this will not -happen. - -=head1 BUGS - -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. - -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 -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. - -The encoding of the TBSCertificate portion of a certificate is cached -in the B<X509> structure internally to improve encoding performance -and to ensure certificate signatures are verified correctly in some -certificates with broken (non-DER) encodings. - -Any function which encodes an X509 structure such as i2d_X509(), -i2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the -B<X509> structure has been modified after deserialization or previous -serialization. - -If, after modification, the B<X509> object is re-signed with X509_sign(), -the encoding is automatically renewed. Otherwise, the encoding of the -TBSCertificate portion of the B<X509> can be manually renewed by calling -i2d_re_X509_tbs(). - -=head1 RETURN VALUES - -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)>. 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 -L<ERR_get_error(3)|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)|ERR_get_error(3)>. - -=head1 SEE ALSO - -L<ERR_get_error(3)|ERR_get_error(3)> - -=head1 HISTORY - -d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp -are available in all versions of SSLeay and OpenSSL. - -=cut |