=head1 SYNOPSIS
- X509 *d2i_X509(X509 **px, unsigned char **in, int len);
+ #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(X509 *x, BIO *bp);
- int i2d_X509_fp(X509 *x, FILE *fp);
+ 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<*out>. 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>
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<*out> 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.
+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
+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>.
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>.
+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>.
+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 that
-B<i2d_X509> converts from internal to DER.
+"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 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
+Functions such as 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
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)
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))
+ if (!d2i_X509(&x, &p, len))
/* Some error */
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.
+Also B<buf> will no longer contain the pointer allocated by OPENSSL_malloc()
+and the subsequent call to 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()>:
+Another trap to avoid is misuse of the B<xp> argument to 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
+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
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
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)>.
+L<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)>.
-i2d_X509(), i2d_X509_bio() and i2d_X509_fp() return a 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)>.
=head1 SEE ALSO
-L<ERR_get_error(3)|ERR_get_error(3)>
+L<ERR_get_error(3)>
+L<X509_CRL_get0_by_serial(3)>,
+L<X509_get0_signature(3)>,
+L<X509_get_ext_d2i(3)>,
+L<X509_get_extension_flags(3)>,
+L<X509_get_pubkey(3)>,
+L<X509_get_subject_name(3)>,
+L<X509_get_version(3)>,
+L<X509_NAME_add_entry_by_txt(3)>,
+L<X509_NAME_ENTRY_get_object(3)>,
+L<X509_NAME_get_index_by_NID(3)>,
+L<X509_NAME_print_ex(3)>,
+L<X509_new(3)>,
+L<X509_sign(3)>,
+L<X509V3_get_d2i(3)>,
+L<X509_verify_cert(3)>
+
+=cut
+
+=head1 COPYRIGHT
-=head1 HISTORY
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
-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.
+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
projects / openssl.git / blobdiff