186229Stmm=pod 286229Stmm 3207243Smarius=head1 NAME 486229Stmm 586229Stmmd2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, 686229Stmmi2d_X509_fp - X509 encode and decode functions 786229Stmm 886229Stmm=head1 SYNOPSIS 986229Stmm 1086229Stmm #include <openssl/x509.h> 1186229Stmm 1286229Stmm X509 *d2i_X509(X509 **px, const unsigned char **in, long len); 1386229Stmm X509 *d2i_X509_AUX(X509 **px, const unsigned char **in, long len); 1486229Stmm int i2d_X509(X509 *x, unsigned char **out); 1586229Stmm int i2d_X509_AUX(X509 *x, unsigned char **out); 1686229Stmm 1786229Stmm X509 *d2i_X509_bio(BIO *bp, X509 **x); 1886229Stmm X509 *d2i_X509_fp(FILE *fp, X509 **x); 1986229Stmm 2086229Stmm int i2d_X509_bio(BIO *bp, X509 *x); 2186229Stmm int i2d_X509_fp(FILE *fp, X509 *x); 2286229Stmm 2386229Stmm int i2d_re_X509_tbs(X509 *x, unsigned char **out); 2486229Stmm 2586229Stmm=head1 DESCRIPTION 26200924Smarius 27146473SmariusThe X509 encode and decode routines encode and parse an 28146473SmariusB<X509> structure, which represents an X509 certificate. 2986229Stmm 3086229Stmmd2i_X509() attempts to decode B<len> bytes at B<*in>. If 31133862Smariussuccessful a pointer to the B<X509> structure is returned. If an error 3286229Stmmoccurred then B<NULL> is returned. If B<px> is not B<NULL> then the 3386229Stmmreturned structure is written to B<*px>. If B<*px> is not B<NULL> 3486229Stmmthen it is assumed that B<*px> contains a valid B<X509> 35133589Smariusstructure and an attempt is made to reuse it. This "reuse" capability is present 3686229Stmmfor historical compatibility but its use is B<strongly discouraged> (see BUGS 3786229Stmmbelow, and the discussion in the RETURN VALUES section). 3888370Stmm 3988370StmmIf the call is successful B<*in> is incremented to the byte following the 40133589Smariusparsed data. 41141753Smarius 42119338Simpd2i_X509_AUX() is similar to d2i_X509() but the input is expected to consist of 4386229Stmman X509 certificate followed by auxiliary trust information. 44119697SmarcelThis is used by the PEM routines to read "TRUSTED CERTIFICATE" objects. 4586229StmmThis function should not be called on untrusted input. 4686229Stmm 4786229Stmmi2d_X509() encodes the structure pointed to by B<x> into DER format. 4886229StmmIf B<out> is not B<NULL> is writes the DER encoded data to the buffer 4986229Stmmat B<*out>, and increments it to point after the data just written. 5086229StmmIf the return value is negative an error occurred, otherwise it 51133728Smariusreturns the length of the encoded data. 5286229Stmm 5386229StmmFor OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be 5486229Stmmallocated for a buffer and the encoded data written to it. In this 55133728Smariuscase B<*out> is not incremented and it points to the start of the 56133728Smariusdata just written. 57133728Smarius 58133728Smariusi2d_X509_AUX() is similar to i2d_X509(), but the encoded output contains both 59133728Smariusthe certificate and any auxiliary trust information. 60133728SmariusThis is used by the PEM routines to write "TRUSTED CERTIFICATE" objects. 61133728SmariusNote, this is a non-standard OpenSSL-specific data format. 62133728Smarius 63133728Smariusd2i_X509_bio() is similar to d2i_X509() except it attempts 64133728Smariusto parse data from BIO B<bp>. 6586229Stmm 6686229Stmmd2i_X509_fp() is similar to d2i_X509() except it attempts 67200924Smariusto parse data from FILE pointer B<fp>. 6888370Stmm 6986229Stmmi2d_X509_bio() is similar to i2d_X509() except it writes 70119697Smarcelthe encoding of the structure B<x> to BIO B<bp> and it 71207243Smariusreturns 1 for success and 0 for failure. 72207243Smarius 73207243Smariusi2d_X509_fp() is similar to i2d_X509() except it writes 74207243Smariusthe encoding of the structure B<x> to BIO B<bp> and it 75207243Smariusreturns 1 for success and 0 for failure. 76207243Smarius 77207243Smariusi2d_re_X509_tbs() is similar to i2d_X509() except it encodes 78207243Smariusonly the TBSCertificate portion of the certificate. 79207243Smarius 80207243Smarius=head1 NOTES 81207243Smarius 82207243SmariusThe letters B<i> and B<d> in for example B<i2d_X509> stand for 83207243Smarius"internal" (that is an internal C structure) and "DER". So 84141753SmariusB<i2d_X509> converts from internal to DER. The "re" in 85141753SmariusB<i2d_re_X509_tbs> stands for "re-encode", and ensures that a fresh 86141753Smariusencoding is generated in case the object has been modified after 87141753Smariuscreation (see the BUGS section). 88141753Smarius 89200924SmariusThe functions can also understand B<BER> forms. 90141753Smarius 91200924SmariusThe actual X509 structure passed to i2d_X509() must be a valid 92141753Smariuspopulated B<X509> structure it can B<not> simply be fed with an 93200924Smariusempty structure such as that returned by X509_new(). 94141753Smarius 95141753SmariusThe encoded data is in binary form and may contain embedded zeroes. 96141753SmariusTherefore any FILE pointers or BIOs should be opened in binary mode. 97141753SmariusFunctions such as B<strlen()> will B<not> return the correct length 98141753Smariusof the encoded structure. 99200924Smarius 100141753SmariusThe ways that B<*in> and B<*out> are incremented after the operation 101141753Smariuscan trap the unwary. See the B<WARNINGS> section for some common 102141753Smariuserrors. 103141753Smarius 104141753SmariusThe reason for the auto increment behaviour is to reflect a typical 105200924Smariususage of ASN1 functions: after one structure is encoded or decoded 106141753Smariusanother will processed after it. 107141753Smarius 108141753Smarius=head1 EXAMPLES 109141753Smarius 110119697SmarcelAllocate and encode the DER encoding of an X509 structure: 111141753Smarius 112119697Smarcel int len; 113119697Smarcel unsigned char *buf, *p; 114200925Smarius 115141753Smarius len = i2d_X509(x, NULL); 116141753Smarius 117141753Smarius buf = OPENSSL_malloc(len); 118200925Smarius 119141753Smarius if (buf == NULL) 120119697Smarcel /* error */ 121141753Smarius 122141753Smarius p = buf; 123200924Smarius 124141753Smarius i2d_X509(x, &p); 125200924Smarius 126200924SmariusIf you are using OpenSSL 0.9.7 or later then this can be 127141753Smariussimplified to: 128200924Smarius 129141753Smarius 130141753Smarius int len; 131141753Smarius unsigned char *buf; 132141753Smarius 133200924Smarius buf = NULL; 134141753Smarius 135141753Smarius len = i2d_X509(x, &buf); 136141753Smarius 137119697Smarcel if (len < 0) 138123866Sobrien /* error */ 139119697Smarcel 140119697SmarcelAttempt to decode a buffer: 141119697Smarcel 142119697Smarcel X509 *x; 143141753Smarius 144141753Smarius unsigned char *buf, *p; 145141753Smarius 146141753Smarius int len; 147146473Smarius 148141753Smarius /* Something to setup buf and len */ 149141753Smarius 150141753Smarius p = buf; 151119697Smarcel 152141753Smarius x = d2i_X509(NULL, &p, len); 153141753Smarius 154141753Smarius if (x == NULL) 155141753Smarius /* Some error */ 156119697Smarcel 157141753SmariusAlternative technique: 158141753Smarius 159141753Smarius X509 *x; 160141753Smarius 161141753Smarius unsigned char *buf, *p; 162141753Smarius 163141753Smarius int len; 164200925Smarius 165200925Smarius /* Something to setup buf and len */ 166200925Smarius 167200925Smarius p = buf; 168141753Smarius 169141753Smarius x = NULL; 170200925Smarius 171141753Smarius if(!d2i_X509(&x, &p, len)) 172141753Smarius /* Some error */ 173200925Smarius 174141753Smarius 175141753Smarius=head1 WARNINGS 176119697Smarcel 177141753SmariusThe use of temporary variable is mandatory. A common 178141753Smariusmistake is to attempt to use a buffer directly as follows: 179141753Smarius 180141753Smarius int len; 181141753Smarius unsigned char *buf; 182141753Smarius 183141753Smarius len = i2d_X509(x, NULL); 184141753Smarius 185141753Smarius buf = OPENSSL_malloc(len); 186141753Smarius 187200925Smarius if (buf == NULL) 188141753Smarius /* error */ 189141753Smarius 190141753Smarius i2d_X509(x, &buf); 191141753Smarius 192141753Smarius /* Other stuff ... */ 193146473Smarius 194141753Smarius OPENSSL_free(buf); 195141753Smarius 196141753SmariusThis code will result in B<buf> apparently containing garbage because 197141753Smariusit was incremented after the call to point after the data just written. 198119697SmarcelAlso B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()> 199141753Smariusand the subsequent call to B<OPENSSL_free()> may well crash. 200141753Smarius 201141753SmariusThe auto allocation feature (setting buf to NULL) only works on OpenSSL 202206448Smarius0.9.7 and later. Attempts to use it on earlier versions will typically 203206448Smariuscause a segmentation violation. 204206448Smarius 205206448SmariusAnother trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: 206141753Smarius 207200925Smarius X509 *x; 208141753Smarius 209200925Smarius if (!d2i_X509(&x, &p, len)) 210200925Smarius /* Some error */ 211200925Smarius 212141753SmariusThis will probably crash somewhere in B<d2i_X509()>. The reason for this 213200925Smariusis that the variable B<x> is uninitialized and an attempt will be made to 214200925Smariusinterpret its (invalid) value as an B<X509> structure, typically causing 215200925Smariusa segmentation violation. If B<x> is set to NULL first then this will not 216141753Smariushappen. 217141753Smarius 218200925Smarius=head1 BUGS 219200925Smarius 220200925SmariusIn some versions of OpenSSL the "reuse" behaviour of d2i_X509() when 221200925SmariusB<*px> is valid is broken and some parts of the reused structure may 222200925Smariuspersist if they are not present in the new one. As a result the use 223200925Smariusof this "reuse" behaviour is strongly discouraged. 224200925Smarius 225200925Smariusi2d_X509() will not return an error in many versions of OpenSSL, 226141753Smariusif mandatory fields are not initialized due to a programming error 227141753Smariusthen the encoded structure may contain invalid data or omit the 228200925Smariusfields entirely and will not be parsed by d2i_X509(). This may be 229141753Smariusfixed in future so code should not assume that i2d_X509() will 230141753Smariusalways succeed. 231141753Smarius 232141753SmariusThe encoding of the TBSCertificate portion of a certificate is cached 233141753Smariusin the B<X509> structure internally to improve encoding performance 234141753Smariusand to ensure certificate signatures are verified correctly in some 235119697Smarcelcertificates with broken (non-DER) encodings. 236119697Smarcel 237119697SmarcelAny function which encodes an X509 structure such as i2d_X509(), 238200925Smariusi2d_X509_fp() or i2d_X509_bio() may return a stale encoding if the 239200925SmariusB<X509> structure has been modified after deserialization or previous 240200925Smariusserialization. 241141753Smarius 242119697SmarcelIf, after modification, the B<X509> object is re-signed with X509_sign(), 243141753Smariusthe encoding is automatically renewed. Otherwise, the encoding of the 244119697SmarcelTBSCertificate portion of the B<X509> can be manually renewed by calling 245206448Smariusi2d_re_X509_tbs(). 246141753Smarius 247141753Smarius=head1 RETURN VALUES 248141753Smarius 249141753Smariusd2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure 250119697Smarcelor B<NULL> if an error occurs. The error code that can be obtained by 251141753SmariusL<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used 252200925Smariuswith a valid X509 structure being passed in via B<px> then the object is not 253166058Smariusfreed in the event of error but may be in a potentially invalid or inconsistent 254166096Smariusstate. 255166058Smarius 256166058Smariusi2d_X509() returns the number of bytes successfully encoded or a negative 257141753Smariusvalue if an error occurs. The error code can be obtained by 258141753SmariusL<ERR_get_error(3)|ERR_get_error(3)>. 259141753Smarius 260200925Smariusi2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error 261200925Smariusoccurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 262166096Smarius 263141753Smarius=head1 SEE ALSO 264141753Smarius 265200925SmariusL<ERR_get_error(3)|ERR_get_error(3)> 266141753Smarius 267141753Smarius=head1 HISTORY 268141753Smarius 269141753Smariusd2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp 270141753Smariusare available in all versions of SSLeay and OpenSSL. 271141753Smarius 272119697Smarcel=cut 273119697Smarcel