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