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