Update files for OpenSSL-1.0.0f import.
[dragonfly.git] / secure / lib / libcrypto / man / d2i_X509.3
CommitLineData
e3261593 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
8b0cefbb
JR
2.\"
3.\" Standard preamble:
4.\" ========================================================================
8b0cefbb 5.de Sp \" Vertical space (when we can't use .PP)
984263bc
MD
6.if t .sp .5v
7.if n .sp
8..
8b0cefbb 9.de Vb \" Begin verbatim text
984263bc
MD
10.ft CW
11.nf
12.ne \\$1
13..
8b0cefbb 14.de Ve \" End verbatim text
984263bc 15.ft R
984263bc
MD
16.fi
17..
8b0cefbb
JR
18.\" Set up some character translations and predefined strings. \*(-- will
19.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
e257b235
PA
20.\" double quote, and \*(R" will give a right double quote. \*(C+ will
21.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
22.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
23.\" nothing in troff, for use with C<>.
24.tr \(*W-
8b0cefbb 25.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
984263bc 26.ie n \{\
8b0cefbb
JR
27. ds -- \(*W-
28. ds PI pi
29. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
30. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
31. ds L" ""
32. ds R" ""
33. ds C` ""
34. ds C' ""
984263bc
MD
35'br\}
36.el\{\
8b0cefbb
JR
37. ds -- \|\(em\|
38. ds PI \(*p
39. ds L" ``
40. ds R" ''
984263bc 41'br\}
8b0cefbb 42.\"
e257b235
PA
43.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq
45.el .ds Aq '
46.\"
8b0cefbb 47.\" If the F register is turned on, we'll generate index entries on stderr for
01185282 48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
8b0cefbb
JR
49.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion.
e257b235 51.ie \nF \{\
8b0cefbb
JR
52. de IX
53. tm Index:\\$1\t\\n%\t"\\$2"
984263bc 54..
8b0cefbb
JR
55. nr % 0
56. rr F
984263bc 57.\}
e257b235
PA
58.el \{\
59. de IX
60..
61.\}
aac4ff6f 62.\"
8b0cefbb
JR
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff
984263bc 66.if n \{\
8b0cefbb
JR
67. ds #H 0
68. ds #V .8m
69. ds #F .3m
70. ds #[ \f1
71. ds #] \fP
984263bc
MD
72.\}
73.if t \{\
8b0cefbb
JR
74. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
75. ds #V .6m
76. ds #F 0
77. ds #[ \&
78. ds #] \&
984263bc 79.\}
8b0cefbb 80. \" simple accents for nroff and troff
984263bc 81.if n \{\
8b0cefbb
JR
82. ds ' \&
83. ds ` \&
84. ds ^ \&
85. ds , \&
86. ds ~ ~
87. ds /
984263bc
MD
88.\}
89.if t \{\
8b0cefbb
JR
90. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
91. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
92. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
93. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
94. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
95. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
984263bc 96.\}
8b0cefbb 97. \" troff and (daisy-wheel) nroff accents
984263bc
MD
98.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
99.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
100.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
101.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
102.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
103.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
104.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
105.ds ae a\h'-(\w'a'u*4/10)'e
106.ds Ae A\h'-(\w'A'u*4/10)'E
8b0cefbb 107. \" corrections for vroff
984263bc
MD
108.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
109.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
8b0cefbb 110. \" for low resolution devices (crt and lpr)
984263bc
MD
111.if \n(.H>23 .if \n(.V>19 \
112\{\
8b0cefbb
JR
113. ds : e
114. ds 8 ss
115. ds o a
116. ds d- d\h'-1'\(ga
117. ds D- D\h'-1'\(hy
118. ds th \o'bp'
119. ds Th \o'LP'
120. ds ae ae
121. ds Ae AE
984263bc
MD
122.\}
123.rm #[ #] #H #V #F C
8b0cefbb
JR
124.\" ========================================================================
125.\"
126.IX Title "d2i_X509 3"
e3261593 127.TH d2i_X509 3 "2012-01-04" "1.0.0f" "OpenSSL"
e257b235
PA
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents.
130.if n .ad l
131.nh
984263bc
MD
132.SH "NAME"
133d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio,
134i2d_X509_fp \- X509 encode and decode functions
135.SH "SYNOPSIS"
8b0cefbb 136.IX Header "SYNOPSIS"
984263bc
MD
137.Vb 1
138\& #include <openssl/x509.h>
e257b235 139\&
c6082640 140\& X509 *d2i_X509(X509 **px, const unsigned char **in, int len);
984263bc 141\& int i2d_X509(X509 *x, unsigned char **out);
e257b235 142\&
984263bc
MD
143\& X509 *d2i_X509_bio(BIO *bp, X509 **x);
144\& X509 *d2i_X509_fp(FILE *fp, X509 **x);
e257b235 145\&
01185282
PA
146\& int i2d_X509_bio(BIO *bp, X509 *x);
147\& int i2d_X509_fp(FILE *fp, X509 *x);
984263bc
MD
148.Ve
149.SH "DESCRIPTION"
8b0cefbb 150.IX Header "DESCRIPTION"
984263bc 151The X509 encode and decode routines encode and parse an
8b0cefbb 152\&\fBX509\fR structure, which represents an X509 certificate.
984263bc 153.PP
a561f9ff 154\&\fId2i_X509()\fR attempts to decode \fBlen\fR bytes at \fB*in\fR. If
984263bc 155successful a pointer to the \fBX509\fR structure is returned. If an error
8b0cefbb
JR
156occurred then \fB\s-1NULL\s0\fR is returned. If \fBpx\fR is not \fB\s-1NULL\s0\fR then the
157returned structure is written to \fB*px\fR. If \fB*px\fR is not \fB\s-1NULL\s0\fR
984263bc
MD
158then it is assumed that \fB*px\fR contains a valid \fBX509\fR
159structure and an attempt is made to reuse it. If the call is
a561f9ff 160successful \fB*in\fR is incremented to the byte following the
984263bc
MD
161parsed data.
162.PP
8b0cefbb
JR
163\&\fIi2d_X509()\fR encodes the structure pointed to by \fBx\fR into \s-1DER\s0 format.
164If \fBout\fR is not \fB\s-1NULL\s0\fR is writes the \s-1DER\s0 encoded data to the buffer
984263bc
MD
165at \fB*out\fR, and increments it to point after the data just written.
166If the return value is negative an error occurred, otherwise it
e257b235 167returns the length of the encoded data.
984263bc 168.PP
8b0cefbb 169For OpenSSL 0.9.7 and later if \fB*out\fR is \fB\s-1NULL\s0\fR memory will be
984263bc
MD
170allocated for a buffer and the encoded data written to it. In this
171case \fB*out\fR is not incremented and it points to the start of the
172data just written.
173.PP
8b0cefbb
JR
174\&\fId2i_X509_bio()\fR is similar to \fId2i_X509()\fR except it attempts
175to parse data from \s-1BIO\s0 \fBbp\fR.
984263bc 176.PP
8b0cefbb
JR
177\&\fId2i_X509_fp()\fR is similar to \fId2i_X509()\fR except it attempts
178to parse data from \s-1FILE\s0 pointer \fBfp\fR.
984263bc 179.PP
8b0cefbb
JR
180\&\fIi2d_X509_bio()\fR is similar to \fIi2d_X509()\fR except it writes
181the encoding of the structure \fBx\fR to \s-1BIO\s0 \fBbp\fR and it
984263bc
MD
182returns 1 for success and 0 for failure.
183.PP
8b0cefbb
JR
184\&\fIi2d_X509_fp()\fR is similar to \fIi2d_X509()\fR except it writes
185the encoding of the structure \fBx\fR to \s-1BIO\s0 \fBbp\fR and it
984263bc
MD
186returns 1 for success and 0 for failure.
187.SH "NOTES"
8b0cefbb 188.IX Header "NOTES"
984263bc 189The letters \fBi\fR and \fBd\fR in for example \fBi2d_X509\fR stand for
8b0cefbb
JR
190\&\*(L"internal\*(R" (that is an internal C structure) and \*(L"\s-1DER\s0\*(R". So that
191\&\fBi2d_X509\fR converts from internal to \s-1DER\s0.
984263bc 192.PP
8b0cefbb 193The functions can also understand \fB\s-1BER\s0\fR forms.
984263bc
MD
194.PP
195The actual X509 structure passed to \fIi2d_X509()\fR must be a valid
196populated \fBX509\fR structure it can \fBnot\fR simply be fed with an
197empty structure such as that returned by \fIX509_new()\fR.
198.PP
199The encoded data is in binary form and may contain embedded zeroes.
8b0cefbb
JR
200Therefore any \s-1FILE\s0 pointers or BIOs should be opened in binary mode.
201Functions such as \fB\f(BIstrlen()\fB\fR will \fBnot\fR return the correct length
984263bc
MD
202of the encoded structure.
203.PP
204The ways that \fB*in\fR and \fB*out\fR are incremented after the operation
8b0cefbb 205can trap the unwary. See the \fB\s-1WARNINGS\s0\fR section for some common
984263bc
MD
206errors.
207.PP
208The reason for the auto increment behaviour is to reflect a typical
8b0cefbb 209usage of \s-1ASN1\s0 functions: after one structure is encoded or decoded
984263bc
MD
210another will processed after it.
211.SH "EXAMPLES"
8b0cefbb
JR
212.IX Header "EXAMPLES"
213Allocate and encode the \s-1DER\s0 encoding of an X509 structure:
984263bc
MD
214.PP
215.Vb 2
216\& int len;
217\& unsigned char *buf, *p;
e257b235 218\&
984263bc 219\& len = i2d_X509(x, NULL);
e257b235 220\&
984263bc 221\& buf = OPENSSL_malloc(len);
e257b235 222\&
984263bc
MD
223\& if (buf == NULL)
224\& /* error */
e257b235 225\&
984263bc 226\& p = buf;
e257b235 227\&
984263bc
MD
228\& i2d_X509(x, &p);
229.Ve
8b0cefbb 230.PP
984263bc
MD
231If you are using OpenSSL 0.9.7 or later then this can be
232simplified to:
233.PP
234.Vb 2
235\& int len;
236\& unsigned char *buf;
e257b235 237\&
984263bc 238\& buf = NULL;
e257b235 239\&
984263bc 240\& len = i2d_X509(x, &buf);
e257b235 241\&
984263bc
MD
242\& if (len < 0)
243\& /* error */
244.Ve
8b0cefbb 245.PP
984263bc
MD
246Attempt to decode a buffer:
247.PP
248.Vb 1
249\& X509 *x;
e257b235 250\&
984263bc 251\& unsigned char *buf, *p;
e257b235 252\&
984263bc 253\& int len;
e257b235 254\&
984263bc 255\& /* Something to setup buf and len */
e257b235 256\&
984263bc 257\& p = buf;
e257b235 258\&
984263bc 259\& x = d2i_X509(NULL, &p, len);
e257b235 260\&
984263bc
MD
261\& if (x == NULL)
262\& /* Some error */
263.Ve
8b0cefbb 264.PP
984263bc
MD
265Alternative technique:
266.PP
267.Vb 1
268\& X509 *x;
e257b235 269\&
984263bc 270\& unsigned char *buf, *p;
e257b235 271\&
984263bc 272\& int len;
e257b235 273\&
984263bc 274\& /* Something to setup buf and len */
e257b235 275\&
984263bc 276\& p = buf;
e257b235 277\&
984263bc 278\& x = NULL;
e257b235 279\&
984263bc
MD
280\& if(!d2i_X509(&x, &p, len))
281\& /* Some error */
282.Ve
283.SH "WARNINGS"
8b0cefbb 284.IX Header "WARNINGS"
984263bc
MD
285The use of temporary variable is mandatory. A common
286mistake is to attempt to use a buffer directly as follows:
287.PP
288.Vb 2
289\& int len;
290\& unsigned char *buf;
e257b235 291\&
984263bc 292\& len = i2d_X509(x, NULL);
e257b235 293\&
984263bc 294\& buf = OPENSSL_malloc(len);
e257b235 295\&
984263bc
MD
296\& if (buf == NULL)
297\& /* error */
e257b235 298\&
984263bc 299\& i2d_X509(x, &buf);
e257b235 300\&
984263bc 301\& /* Other stuff ... */
e257b235 302\&
984263bc
MD
303\& OPENSSL_free(buf);
304.Ve
8b0cefbb 305.PP
984263bc
MD
306This code will result in \fBbuf\fR apparently containing garbage because
307it was incremented after the call to point after the data just written.
8b0cefbb
JR
308Also \fBbuf\fR will no longer contain the pointer allocated by \fB\f(BIOPENSSL_malloc()\fB\fR
309and the subsequent call to \fB\f(BIOPENSSL_free()\fB\fR may well crash.
984263bc 310.PP
8b0cefbb 311The auto allocation feature (setting buf to \s-1NULL\s0) only works on OpenSSL
984263bc
MD
3120.9.7 and later. Attempts to use it on earlier versions will typically
313cause a segmentation violation.
314.PP
8b0cefbb 315Another trap to avoid is misuse of the \fBxp\fR argument to \fB\f(BId2i_X509()\fB\fR:
984263bc
MD
316.PP
317.Vb 1
318\& X509 *x;
e257b235 319\&
984263bc
MD
320\& if (!d2i_X509(&x, &p, len))
321\& /* Some error */
322.Ve
8b0cefbb
JR
323.PP
324This will probably crash somewhere in \fB\f(BId2i_X509()\fB\fR. The reason for this
984263bc
MD
325is that the variable \fBx\fR is uninitialized and an attempt will be made to
326interpret its (invalid) value as an \fBX509\fR structure, typically causing
8b0cefbb 327a segmentation violation. If \fBx\fR is set to \s-1NULL\s0 first then this will not
984263bc
MD
328happen.
329.SH "BUGS"
8b0cefbb 330.IX Header "BUGS"
984263bc 331In some versions of OpenSSL the \*(L"reuse\*(R" behaviour of \fId2i_X509()\fR when
8b0cefbb 332\&\fB*px\fR is valid is broken and some parts of the reused structure may
984263bc
MD
333persist if they are not present in the new one. As a result the use
334of this \*(L"reuse\*(R" behaviour is strongly discouraged.
335.PP
8b0cefbb 336\&\fIi2d_X509()\fR will not return an error in many versions of OpenSSL,
984263bc
MD
337if mandatory fields are not initialized due to a programming error
338then the encoded structure may contain invalid data or omit the
339fields entirely and will not be parsed by \fId2i_X509()\fR. This may be
340fixed in future so code should not assume that \fIi2d_X509()\fR will
341always succeed.
342.SH "RETURN VALUES"
8b0cefbb
JR
343.IX Header "RETURN VALUES"
344\&\fId2i_X509()\fR, \fId2i_X509_bio()\fR and \fId2i_X509_fp()\fR return a valid \fBX509\fR structure
345or \fB\s-1NULL\s0\fR if an error occurs. The error code that can be obtained by
e257b235 346\&\fIERR_get_error\fR\|(3).
984263bc 347.PP
01185282
PA
348\&\fIi2d_X509()\fR returns the number of bytes successfully encoded or a negative
349value if an error occurs. The error code can be obtained by
350\&\fIERR_get_error\fR\|(3).
984263bc 351.PP
01185282 352\&\fIi2d_X509_bio()\fR and \fIi2d_X509_fp()\fR return 1 for success and 0 if an error
e257b235 353occurs The error code can be obtained by \fIERR_get_error\fR\|(3).
984263bc 354.SH "SEE ALSO"
8b0cefbb
JR
355.IX Header "SEE ALSO"
356\&\fIERR_get_error\fR\|(3)
984263bc 357.SH "HISTORY"
8b0cefbb 358.IX Header "HISTORY"
984263bc
MD
359d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio and i2d_X509_fp
360are available in all versions of SSLeay and OpenSSL.