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