d2i_X509.pod 6.3 KB

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