1ebfedea0SLionel Sambuc=pod 2ebfedea0SLionel Sambuc 3ebfedea0SLionel Sambuc=head1 NAME 4ebfedea0SLionel Sambuc 5ebfedea0SLionel Sambucd2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, 6ebfedea0SLionel Sambuci2d_X509_fp - X509 encode and decode functions 7ebfedea0SLionel Sambuc 8ebfedea0SLionel Sambuc=head1 SYNOPSIS 9ebfedea0SLionel Sambuc 10ebfedea0SLionel Sambuc #include <openssl/x509.h> 11ebfedea0SLionel Sambuc 12ebfedea0SLionel Sambuc X509 *d2i_X509(X509 **px, const unsigned char **in, int len); 13ebfedea0SLionel Sambuc int i2d_X509(X509 *x, unsigned char **out); 14ebfedea0SLionel Sambuc 15ebfedea0SLionel Sambuc X509 *d2i_X509_bio(BIO *bp, X509 **x); 16ebfedea0SLionel Sambuc X509 *d2i_X509_fp(FILE *fp, X509 **x); 17ebfedea0SLionel Sambuc 18ebfedea0SLionel Sambuc int i2d_X509_bio(BIO *bp, X509 *x); 19ebfedea0SLionel Sambuc int i2d_X509_fp(FILE *fp, X509 *x); 20ebfedea0SLionel Sambuc 21ebfedea0SLionel Sambuc=head1 DESCRIPTION 22ebfedea0SLionel Sambuc 23ebfedea0SLionel SambucThe X509 encode and decode routines encode and parse an 24ebfedea0SLionel SambucB<X509> structure, which represents an X509 certificate. 25ebfedea0SLionel Sambuc 26ebfedea0SLionel Sambucd2i_X509() attempts to decode B<len> bytes at B<*in>. If 27ebfedea0SLionel Sambucsuccessful a pointer to the B<X509> structure is returned. If an error 28ebfedea0SLionel Sambucoccurred then B<NULL> is returned. If B<px> is not B<NULL> then the 29ebfedea0SLionel Sambucreturned structure is written to B<*px>. If B<*px> is not B<NULL> 30ebfedea0SLionel Sambucthen it is assumed that B<*px> contains a valid B<X509> 31*0a6a1f1dSLionel Sambucstructure and an attempt is made to reuse it. This "reuse" capability is present 32*0a6a1f1dSLionel Sambucfor historical compatibility but its use is B<strongly discouraged> (see BUGS 33*0a6a1f1dSLionel Sambucbelow, and the discussion in the RETURN VALUES section). 34*0a6a1f1dSLionel Sambuc 35*0a6a1f1dSLionel SambucIf the call is successful B<*in> is incremented to the byte following the 36ebfedea0SLionel Sambucparsed data. 37ebfedea0SLionel Sambuc 38ebfedea0SLionel Sambuci2d_X509() encodes the structure pointed to by B<x> into DER format. 39ebfedea0SLionel SambucIf B<out> is not B<NULL> is writes the DER encoded data to the buffer 40ebfedea0SLionel Sambucat B<*out>, and increments it to point after the data just written. 41ebfedea0SLionel SambucIf the return value is negative an error occurred, otherwise it 42ebfedea0SLionel Sambucreturns the length of the encoded data. 43ebfedea0SLionel Sambuc 44ebfedea0SLionel SambucFor OpenSSL 0.9.7 and later if B<*out> is B<NULL> memory will be 45ebfedea0SLionel Sambucallocated for a buffer and the encoded data written to it. In this 46ebfedea0SLionel Sambuccase B<*out> is not incremented and it points to the start of the 47ebfedea0SLionel Sambucdata just written. 48ebfedea0SLionel Sambuc 49ebfedea0SLionel Sambucd2i_X509_bio() is similar to d2i_X509() except it attempts 50ebfedea0SLionel Sambucto parse data from BIO B<bp>. 51ebfedea0SLionel Sambuc 52ebfedea0SLionel Sambucd2i_X509_fp() is similar to d2i_X509() except it attempts 53ebfedea0SLionel Sambucto parse data from FILE pointer B<fp>. 54ebfedea0SLionel Sambuc 55ebfedea0SLionel Sambuci2d_X509_bio() is similar to i2d_X509() except it writes 56ebfedea0SLionel Sambucthe encoding of the structure B<x> to BIO B<bp> and it 57ebfedea0SLionel Sambucreturns 1 for success and 0 for failure. 58ebfedea0SLionel Sambuc 59ebfedea0SLionel Sambuci2d_X509_fp() is similar to i2d_X509() except it writes 60ebfedea0SLionel Sambucthe encoding of the structure B<x> to BIO B<bp> and it 61ebfedea0SLionel Sambucreturns 1 for success and 0 for failure. 62ebfedea0SLionel Sambuc 63ebfedea0SLionel Sambuc=head1 NOTES 64ebfedea0SLionel Sambuc 65ebfedea0SLionel SambucThe letters B<i> and B<d> in for example B<i2d_X509> stand for 66ebfedea0SLionel Sambuc"internal" (that is an internal C structure) and "DER". So that 67ebfedea0SLionel SambucB<i2d_X509> converts from internal to DER. 68ebfedea0SLionel Sambuc 69ebfedea0SLionel SambucThe functions can also understand B<BER> forms. 70ebfedea0SLionel Sambuc 71ebfedea0SLionel SambucThe actual X509 structure passed to i2d_X509() must be a valid 72ebfedea0SLionel Sambucpopulated B<X509> structure it can B<not> simply be fed with an 73ebfedea0SLionel Sambucempty structure such as that returned by X509_new(). 74ebfedea0SLionel Sambuc 75ebfedea0SLionel SambucThe encoded data is in binary form and may contain embedded zeroes. 76ebfedea0SLionel SambucTherefore any FILE pointers or BIOs should be opened in binary mode. 77ebfedea0SLionel SambucFunctions such as B<strlen()> will B<not> return the correct length 78ebfedea0SLionel Sambucof the encoded structure. 79ebfedea0SLionel Sambuc 80ebfedea0SLionel SambucThe ways that B<*in> and B<*out> are incremented after the operation 81ebfedea0SLionel Sambuccan trap the unwary. See the B<WARNINGS> section for some common 82ebfedea0SLionel Sambucerrors. 83ebfedea0SLionel Sambuc 84ebfedea0SLionel SambucThe reason for the auto increment behaviour is to reflect a typical 85ebfedea0SLionel Sambucusage of ASN1 functions: after one structure is encoded or decoded 86ebfedea0SLionel Sambucanother will processed after it. 87ebfedea0SLionel Sambuc 88ebfedea0SLionel Sambuc=head1 EXAMPLES 89ebfedea0SLionel Sambuc 90ebfedea0SLionel SambucAllocate and encode the DER encoding of an X509 structure: 91ebfedea0SLionel Sambuc 92ebfedea0SLionel Sambuc int len; 93ebfedea0SLionel Sambuc unsigned char *buf, *p; 94ebfedea0SLionel Sambuc 95ebfedea0SLionel Sambuc len = i2d_X509(x, NULL); 96ebfedea0SLionel Sambuc 97ebfedea0SLionel Sambuc buf = OPENSSL_malloc(len); 98ebfedea0SLionel Sambuc 99ebfedea0SLionel Sambuc if (buf == NULL) 100ebfedea0SLionel Sambuc /* error */ 101ebfedea0SLionel Sambuc 102ebfedea0SLionel Sambuc p = buf; 103ebfedea0SLionel Sambuc 104ebfedea0SLionel Sambuc i2d_X509(x, &p); 105ebfedea0SLionel Sambuc 106ebfedea0SLionel SambucIf you are using OpenSSL 0.9.7 or later then this can be 107ebfedea0SLionel Sambucsimplified to: 108ebfedea0SLionel Sambuc 109ebfedea0SLionel Sambuc 110ebfedea0SLionel Sambuc int len; 111ebfedea0SLionel Sambuc unsigned char *buf; 112ebfedea0SLionel Sambuc 113ebfedea0SLionel Sambuc buf = NULL; 114ebfedea0SLionel Sambuc 115ebfedea0SLionel Sambuc len = i2d_X509(x, &buf); 116ebfedea0SLionel Sambuc 117ebfedea0SLionel Sambuc if (len < 0) 118ebfedea0SLionel Sambuc /* error */ 119ebfedea0SLionel Sambuc 120ebfedea0SLionel SambucAttempt to decode a buffer: 121ebfedea0SLionel Sambuc 122ebfedea0SLionel Sambuc X509 *x; 123ebfedea0SLionel Sambuc 124ebfedea0SLionel Sambuc unsigned char *buf, *p; 125ebfedea0SLionel Sambuc 126ebfedea0SLionel Sambuc int len; 127ebfedea0SLionel Sambuc 128ebfedea0SLionel Sambuc /* Something to setup buf and len */ 129ebfedea0SLionel Sambuc 130ebfedea0SLionel Sambuc p = buf; 131ebfedea0SLionel Sambuc 132ebfedea0SLionel Sambuc x = d2i_X509(NULL, &p, len); 133ebfedea0SLionel Sambuc 134ebfedea0SLionel Sambuc if (x == NULL) 135ebfedea0SLionel Sambuc /* Some error */ 136ebfedea0SLionel Sambuc 137ebfedea0SLionel SambucAlternative technique: 138ebfedea0SLionel Sambuc 139ebfedea0SLionel Sambuc X509 *x; 140ebfedea0SLionel Sambuc 141ebfedea0SLionel Sambuc unsigned char *buf, *p; 142ebfedea0SLionel Sambuc 143ebfedea0SLionel Sambuc int len; 144ebfedea0SLionel Sambuc 145ebfedea0SLionel Sambuc /* Something to setup buf and len */ 146ebfedea0SLionel Sambuc 147ebfedea0SLionel Sambuc p = buf; 148ebfedea0SLionel Sambuc 149ebfedea0SLionel Sambuc x = NULL; 150ebfedea0SLionel Sambuc 151ebfedea0SLionel Sambuc if(!d2i_X509(&x, &p, len)) 152ebfedea0SLionel Sambuc /* Some error */ 153ebfedea0SLionel Sambuc 154ebfedea0SLionel Sambuc 155ebfedea0SLionel Sambuc=head1 WARNINGS 156ebfedea0SLionel Sambuc 157ebfedea0SLionel SambucThe use of temporary variable is mandatory. A common 158ebfedea0SLionel Sambucmistake is to attempt to use a buffer directly as follows: 159ebfedea0SLionel Sambuc 160ebfedea0SLionel Sambuc int len; 161ebfedea0SLionel Sambuc unsigned char *buf; 162ebfedea0SLionel Sambuc 163ebfedea0SLionel Sambuc len = i2d_X509(x, NULL); 164ebfedea0SLionel Sambuc 165ebfedea0SLionel Sambuc buf = OPENSSL_malloc(len); 166ebfedea0SLionel Sambuc 167ebfedea0SLionel Sambuc if (buf == NULL) 168ebfedea0SLionel Sambuc /* error */ 169ebfedea0SLionel Sambuc 170ebfedea0SLionel Sambuc i2d_X509(x, &buf); 171ebfedea0SLionel Sambuc 172ebfedea0SLionel Sambuc /* Other stuff ... */ 173ebfedea0SLionel Sambuc 174ebfedea0SLionel Sambuc OPENSSL_free(buf); 175ebfedea0SLionel Sambuc 176ebfedea0SLionel SambucThis code will result in B<buf> apparently containing garbage because 177ebfedea0SLionel Sambucit was incremented after the call to point after the data just written. 178ebfedea0SLionel SambucAlso B<buf> will no longer contain the pointer allocated by B<OPENSSL_malloc()> 179ebfedea0SLionel Sambucand the subsequent call to B<OPENSSL_free()> may well crash. 180ebfedea0SLionel Sambuc 181ebfedea0SLionel SambucThe auto allocation feature (setting buf to NULL) only works on OpenSSL 182ebfedea0SLionel Sambuc0.9.7 and later. Attempts to use it on earlier versions will typically 183ebfedea0SLionel Sambuccause a segmentation violation. 184ebfedea0SLionel Sambuc 185ebfedea0SLionel SambucAnother trap to avoid is misuse of the B<xp> argument to B<d2i_X509()>: 186ebfedea0SLionel Sambuc 187ebfedea0SLionel Sambuc X509 *x; 188ebfedea0SLionel Sambuc 189ebfedea0SLionel Sambuc if (!d2i_X509(&x, &p, len)) 190ebfedea0SLionel Sambuc /* Some error */ 191ebfedea0SLionel Sambuc 192ebfedea0SLionel SambucThis will probably crash somewhere in B<d2i_X509()>. The reason for this 193ebfedea0SLionel Sambucis that the variable B<x> is uninitialized and an attempt will be made to 194ebfedea0SLionel Sambucinterpret its (invalid) value as an B<X509> structure, typically causing 195ebfedea0SLionel Sambuca segmentation violation. If B<x> is set to NULL first then this will not 196ebfedea0SLionel Sambuchappen. 197ebfedea0SLionel Sambuc 198ebfedea0SLionel Sambuc=head1 BUGS 199ebfedea0SLionel Sambuc 200ebfedea0SLionel SambucIn some versions of OpenSSL the "reuse" behaviour of d2i_X509() when 201ebfedea0SLionel SambucB<*px> is valid is broken and some parts of the reused structure may 202ebfedea0SLionel Sambucpersist if they are not present in the new one. As a result the use 203ebfedea0SLionel Sambucof this "reuse" behaviour is strongly discouraged. 204ebfedea0SLionel Sambuc 205ebfedea0SLionel Sambuci2d_X509() will not return an error in many versions of OpenSSL, 206ebfedea0SLionel Sambucif mandatory fields are not initialized due to a programming error 207ebfedea0SLionel Sambucthen the encoded structure may contain invalid data or omit the 208ebfedea0SLionel Sambucfields entirely and will not be parsed by d2i_X509(). This may be 209ebfedea0SLionel Sambucfixed in future so code should not assume that i2d_X509() will 210ebfedea0SLionel Sambucalways succeed. 211ebfedea0SLionel Sambuc 212ebfedea0SLionel Sambuc=head1 RETURN VALUES 213ebfedea0SLionel Sambuc 214ebfedea0SLionel Sambucd2i_X509(), d2i_X509_bio() and d2i_X509_fp() return a valid B<X509> structure 215ebfedea0SLionel Sambucor B<NULL> if an error occurs. The error code that can be obtained by 216*0a6a1f1dSLionel SambucL<ERR_get_error(3)|ERR_get_error(3)>. If the "reuse" capability has been used 217*0a6a1f1dSLionel Sambucwith a valid X509 structure being passed in via B<px> then the object is not 218*0a6a1f1dSLionel Sambucfreed in the event of error but may be in a potentially invalid or inconsistent 219*0a6a1f1dSLionel Sambucstate. 220ebfedea0SLionel Sambuc 221ebfedea0SLionel Sambuci2d_X509() returns the number of bytes successfully encoded or a negative 222ebfedea0SLionel Sambucvalue if an error occurs. The error code can be obtained by 223ebfedea0SLionel SambucL<ERR_get_error(3)|ERR_get_error(3)>. 224ebfedea0SLionel Sambuc 225ebfedea0SLionel Sambuci2d_X509_bio() and i2d_X509_fp() return 1 for success and 0 if an error 226ebfedea0SLionel Sambucoccurs The error code can be obtained by L<ERR_get_error(3)|ERR_get_error(3)>. 227ebfedea0SLionel Sambuc 228ebfedea0SLionel Sambuc=head1 SEE ALSO 229ebfedea0SLionel Sambuc 230ebfedea0SLionel SambucL<ERR_get_error(3)|ERR_get_error(3)> 231ebfedea0SLionel Sambuc 232ebfedea0SLionel Sambuc=head1 HISTORY 233ebfedea0SLionel Sambuc 234ebfedea0SLionel Sambucd2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp 235ebfedea0SLionel Sambucare available in all versions of SSLeay and OpenSSL. 236ebfedea0SLionel Sambuc 237ebfedea0SLionel Sambuc=cut 238