doc/crypto/d2i_X509.pod

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