]>
Commit | Line | Data |
---|---|---|
9946fceb DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
4692340e | 5 | d2i_ACCESS_DESCRIPTION, |
fa743582 RS |
6 | d2i_ADMISSIONS, |
7 | d2i_ADMISSION_SYNTAX, | |
4692340e RS |
8 | d2i_ASIdOrRange, |
9 | d2i_ASIdentifierChoice, | |
10 | d2i_ASIdentifiers, | |
11 | d2i_ASN1_BIT_STRING, | |
12 | d2i_ASN1_BMPSTRING, | |
13 | d2i_ASN1_ENUMERATED, | |
14 | d2i_ASN1_GENERALIZEDTIME, | |
15 | d2i_ASN1_GENERALSTRING, | |
16 | d2i_ASN1_IA5STRING, | |
17 | d2i_ASN1_INTEGER, | |
18 | d2i_ASN1_NULL, | |
19 | d2i_ASN1_OBJECT, | |
20 | d2i_ASN1_OCTET_STRING, | |
21 | d2i_ASN1_PRINTABLE, | |
22 | d2i_ASN1_PRINTABLESTRING, | |
23 | d2i_ASN1_SEQUENCE_ANY, | |
24 | d2i_ASN1_SET_ANY, | |
25 | d2i_ASN1_T61STRING, | |
26 | d2i_ASN1_TIME, | |
27 | d2i_ASN1_TYPE, | |
28 | d2i_ASN1_UINTEGER, | |
29 | d2i_ASN1_UNIVERSALSTRING, | |
30 | d2i_ASN1_UTCTIME, | |
31 | d2i_ASN1_UTF8STRING, | |
32 | d2i_ASN1_VISIBLESTRING, | |
33 | d2i_ASRange, | |
34 | d2i_AUTHORITY_INFO_ACCESS, | |
35 | d2i_AUTHORITY_KEYID, | |
36 | d2i_BASIC_CONSTRAINTS, | |
37 | d2i_CERTIFICATEPOLICIES, | |
38 | d2i_CMS_ContentInfo, | |
39 | d2i_CMS_ReceiptRequest, | |
40 | d2i_CMS_bio, | |
41 | d2i_CRL_DIST_POINTS, | |
42 | d2i_DHxparams, | |
43 | d2i_DIRECTORYSTRING, | |
44 | d2i_DISPLAYTEXT, | |
45 | d2i_DIST_POINT, | |
46 | d2i_DIST_POINT_NAME, | |
47 | d2i_DSAPrivateKey, | |
48 | d2i_DSAPrivateKey_bio, | |
49 | d2i_DSAPrivateKey_fp, | |
50 | d2i_DSAPublicKey, | |
82d89ef7 | 51 | d2i_DSA_PUBKEY, |
4692340e RS |
52 | d2i_DSA_PUBKEY_bio, |
53 | d2i_DSA_PUBKEY_fp, | |
54 | d2i_DSA_SIG, | |
55 | d2i_DSAparams, | |
bbda7997 | 56 | d2i_ECDSA_SIG, |
4692340e RS |
57 | d2i_ECPKParameters, |
58 | d2i_ECParameters, | |
59 | d2i_ECPrivateKey, | |
60 | d2i_ECPrivateKey_bio, | |
61 | d2i_ECPrivateKey_fp, | |
62 | d2i_EC_PUBKEY, | |
63 | d2i_EC_PUBKEY_bio, | |
64 | d2i_EC_PUBKEY_fp, | |
65 | d2i_EDIPARTYNAME, | |
66 | d2i_ESS_CERT_ID, | |
8c00f267 | 67 | d2i_ESS_CERT_ID_V2, |
4692340e RS |
68 | d2i_ESS_ISSUER_SERIAL, |
69 | d2i_ESS_SIGNING_CERT, | |
8c00f267 | 70 | d2i_ESS_SIGNING_CERT_V2, |
4692340e RS |
71 | d2i_EXTENDED_KEY_USAGE, |
72 | d2i_GENERAL_NAME, | |
73 | d2i_GENERAL_NAMES, | |
74 | d2i_IPAddressChoice, | |
75 | d2i_IPAddressFamily, | |
76 | d2i_IPAddressOrRange, | |
77 | d2i_IPAddressRange, | |
78 | d2i_ISSUING_DIST_POINT, | |
fa743582 | 79 | d2i_NAMING_AUTHORITY, |
4692340e RS |
80 | d2i_NETSCAPE_CERT_SEQUENCE, |
81 | d2i_NETSCAPE_SPKAC, | |
82 | d2i_NETSCAPE_SPKI, | |
83 | d2i_NOTICEREF, | |
84 | d2i_OCSP_BASICRESP, | |
85 | d2i_OCSP_CERTID, | |
86 | d2i_OCSP_CERTSTATUS, | |
87 | d2i_OCSP_CRLID, | |
88 | d2i_OCSP_ONEREQ, | |
89 | d2i_OCSP_REQINFO, | |
90 | d2i_OCSP_REQUEST, | |
91 | d2i_OCSP_RESPBYTES, | |
92 | d2i_OCSP_RESPDATA, | |
93 | d2i_OCSP_RESPID, | |
94 | d2i_OCSP_RESPONSE, | |
95 | d2i_OCSP_REVOKEDINFO, | |
96 | d2i_OCSP_SERVICELOC, | |
97 | d2i_OCSP_SIGNATURE, | |
98 | d2i_OCSP_SINGLERESP, | |
8869ad4a AK |
99 | d2i_OSSL_CMP_MSG, |
100 | d2i_OSSL_CMP_PKIHEADER, | |
101 | d2i_OSSL_CRMF_CERTID, | |
102 | d2i_OSSL_CRMF_CERTTEMPLATE, | |
103 | d2i_OSSL_CRMF_ENCRYPTEDVALUE, | |
104 | d2i_OSSL_CRMF_MSG, | |
105 | d2i_OSSL_CRMF_MSGS, | |
106 | d2i_OSSL_CRMF_PBMPARAMETER, | |
107 | d2i_OSSL_CRMF_PKIPUBLICATIONINFO, | |
108 | d2i_OSSL_CRMF_SINGLEPUBINFO, | |
4692340e RS |
109 | d2i_OTHERNAME, |
110 | d2i_PBE2PARAM, | |
111 | d2i_PBEPARAM, | |
112 | d2i_PBKDF2PARAM, | |
113 | d2i_PKCS12, | |
114 | d2i_PKCS12_BAGS, | |
115 | d2i_PKCS12_MAC_DATA, | |
116 | d2i_PKCS12_SAFEBAG, | |
117 | d2i_PKCS12_bio, | |
118 | d2i_PKCS12_fp, | |
119 | d2i_PKCS7, | |
120 | d2i_PKCS7_DIGEST, | |
121 | d2i_PKCS7_ENCRYPT, | |
122 | d2i_PKCS7_ENC_CONTENT, | |
123 | d2i_PKCS7_ENVELOPE, | |
124 | d2i_PKCS7_ISSUER_AND_SERIAL, | |
125 | d2i_PKCS7_RECIP_INFO, | |
126 | d2i_PKCS7_SIGNED, | |
127 | d2i_PKCS7_SIGNER_INFO, | |
128 | d2i_PKCS7_SIGN_ENVELOPE, | |
129 | d2i_PKCS7_bio, | |
130 | d2i_PKCS7_fp, | |
131 | d2i_PKCS8_PRIV_KEY_INFO, | |
132 | d2i_PKCS8_PRIV_KEY_INFO_bio, | |
133 | d2i_PKCS8_PRIV_KEY_INFO_fp, | |
134 | d2i_PKCS8_bio, | |
135 | d2i_PKCS8_fp, | |
136 | d2i_PKEY_USAGE_PERIOD, | |
137 | d2i_POLICYINFO, | |
138 | d2i_POLICYQUALINFO, | |
fa743582 | 139 | d2i_PROFESSION_INFO, |
4692340e RS |
140 | d2i_PROXY_CERT_INFO_EXTENSION, |
141 | d2i_PROXY_POLICY, | |
4692340e RS |
142 | d2i_RSAPrivateKey, |
143 | d2i_RSAPrivateKey_bio, | |
144 | d2i_RSAPrivateKey_fp, | |
145 | d2i_RSAPublicKey, | |
146 | d2i_RSAPublicKey_bio, | |
147 | d2i_RSAPublicKey_fp, | |
148 | d2i_RSA_OAEP_PARAMS, | |
149 | d2i_RSA_PSS_PARAMS, | |
150 | d2i_RSA_PUBKEY, | |
151 | d2i_RSA_PUBKEY_bio, | |
152 | d2i_RSA_PUBKEY_fp, | |
00606b06 | 153 | d2i_SCRYPT_PARAMS, |
4692340e RS |
154 | d2i_SCT_LIST, |
155 | d2i_SXNET, | |
156 | d2i_SXNETID, | |
157 | d2i_TS_ACCURACY, | |
158 | d2i_TS_MSG_IMPRINT, | |
159 | d2i_TS_MSG_IMPRINT_bio, | |
160 | d2i_TS_MSG_IMPRINT_fp, | |
161 | d2i_TS_REQ, | |
162 | d2i_TS_REQ_bio, | |
163 | d2i_TS_REQ_fp, | |
164 | d2i_TS_RESP, | |
165 | d2i_TS_RESP_bio, | |
166 | d2i_TS_RESP_fp, | |
167 | d2i_TS_STATUS_INFO, | |
168 | d2i_TS_TST_INFO, | |
169 | d2i_TS_TST_INFO_bio, | |
170 | d2i_TS_TST_INFO_fp, | |
171 | d2i_USERNOTICE, | |
172 | d2i_X509, | |
173 | d2i_X509_ALGOR, | |
174 | d2i_X509_ALGORS, | |
175 | d2i_X509_ATTRIBUTE, | |
176 | d2i_X509_CERT_AUX, | |
177 | d2i_X509_CINF, | |
178 | d2i_X509_CRL, | |
179 | d2i_X509_CRL_INFO, | |
180 | d2i_X509_CRL_bio, | |
181 | d2i_X509_CRL_fp, | |
182 | d2i_X509_EXTENSION, | |
183 | d2i_X509_EXTENSIONS, | |
184 | d2i_X509_NAME, | |
185 | d2i_X509_NAME_ENTRY, | |
186 | d2i_X509_PUBKEY, | |
187 | d2i_X509_REQ, | |
188 | d2i_X509_REQ_INFO, | |
189 | d2i_X509_REQ_bio, | |
190 | d2i_X509_REQ_fp, | |
191 | d2i_X509_REVOKED, | |
192 | d2i_X509_SIG, | |
193 | d2i_X509_VAL, | |
194 | i2d_ACCESS_DESCRIPTION, | |
fa743582 RS |
195 | i2d_ADMISSIONS, |
196 | i2d_ADMISSION_SYNTAX, | |
4692340e RS |
197 | i2d_ASIdOrRange, |
198 | i2d_ASIdentifierChoice, | |
199 | i2d_ASIdentifiers, | |
200 | i2d_ASN1_BIT_STRING, | |
201 | i2d_ASN1_BMPSTRING, | |
202 | i2d_ASN1_ENUMERATED, | |
203 | i2d_ASN1_GENERALIZEDTIME, | |
204 | i2d_ASN1_GENERALSTRING, | |
205 | i2d_ASN1_IA5STRING, | |
206 | i2d_ASN1_INTEGER, | |
207 | i2d_ASN1_NULL, | |
208 | i2d_ASN1_OBJECT, | |
209 | i2d_ASN1_OCTET_STRING, | |
210 | i2d_ASN1_PRINTABLE, | |
211 | i2d_ASN1_PRINTABLESTRING, | |
212 | i2d_ASN1_SEQUENCE_ANY, | |
213 | i2d_ASN1_SET_ANY, | |
214 | i2d_ASN1_T61STRING, | |
215 | i2d_ASN1_TIME, | |
216 | i2d_ASN1_TYPE, | |
217 | i2d_ASN1_UNIVERSALSTRING, | |
218 | i2d_ASN1_UTCTIME, | |
219 | i2d_ASN1_UTF8STRING, | |
220 | i2d_ASN1_VISIBLESTRING, | |
221 | i2d_ASN1_bio_stream, | |
222 | i2d_ASRange, | |
223 | i2d_AUTHORITY_INFO_ACCESS, | |
224 | i2d_AUTHORITY_KEYID, | |
225 | i2d_BASIC_CONSTRAINTS, | |
226 | i2d_CERTIFICATEPOLICIES, | |
227 | i2d_CMS_ContentInfo, | |
228 | i2d_CMS_ReceiptRequest, | |
229 | i2d_CMS_bio, | |
230 | i2d_CRL_DIST_POINTS, | |
231 | i2d_DHxparams, | |
232 | i2d_DIRECTORYSTRING, | |
233 | i2d_DISPLAYTEXT, | |
234 | i2d_DIST_POINT, | |
235 | i2d_DIST_POINT_NAME, | |
236 | i2d_DSAPrivateKey, | |
237 | i2d_DSAPrivateKey_bio, | |
238 | i2d_DSAPrivateKey_fp, | |
239 | i2d_DSAPublicKey, | |
82d89ef7 | 240 | i2d_DSA_PUBKEY, |
4692340e RS |
241 | i2d_DSA_PUBKEY_bio, |
242 | i2d_DSA_PUBKEY_fp, | |
243 | i2d_DSA_SIG, | |
244 | i2d_DSAparams, | |
bbda7997 | 245 | i2d_ECDSA_SIG, |
4692340e RS |
246 | i2d_ECPKParameters, |
247 | i2d_ECParameters, | |
248 | i2d_ECPrivateKey, | |
249 | i2d_ECPrivateKey_bio, | |
250 | i2d_ECPrivateKey_fp, | |
251 | i2d_EC_PUBKEY, | |
252 | i2d_EC_PUBKEY_bio, | |
253 | i2d_EC_PUBKEY_fp, | |
254 | i2d_EDIPARTYNAME, | |
255 | i2d_ESS_CERT_ID, | |
8c00f267 | 256 | i2d_ESS_CERT_ID_V2, |
4692340e RS |
257 | i2d_ESS_ISSUER_SERIAL, |
258 | i2d_ESS_SIGNING_CERT, | |
8c00f267 | 259 | i2d_ESS_SIGNING_CERT_V2, |
4692340e RS |
260 | i2d_EXTENDED_KEY_USAGE, |
261 | i2d_GENERAL_NAME, | |
262 | i2d_GENERAL_NAMES, | |
263 | i2d_IPAddressChoice, | |
264 | i2d_IPAddressFamily, | |
265 | i2d_IPAddressOrRange, | |
266 | i2d_IPAddressRange, | |
267 | i2d_ISSUING_DIST_POINT, | |
fa743582 | 268 | i2d_NAMING_AUTHORITY, |
4692340e RS |
269 | i2d_NETSCAPE_CERT_SEQUENCE, |
270 | i2d_NETSCAPE_SPKAC, | |
271 | i2d_NETSCAPE_SPKI, | |
272 | i2d_NOTICEREF, | |
273 | i2d_OCSP_BASICRESP, | |
274 | i2d_OCSP_CERTID, | |
275 | i2d_OCSP_CERTSTATUS, | |
276 | i2d_OCSP_CRLID, | |
277 | i2d_OCSP_ONEREQ, | |
278 | i2d_OCSP_REQINFO, | |
279 | i2d_OCSP_REQUEST, | |
280 | i2d_OCSP_RESPBYTES, | |
281 | i2d_OCSP_RESPDATA, | |
282 | i2d_OCSP_RESPID, | |
283 | i2d_OCSP_RESPONSE, | |
284 | i2d_OCSP_REVOKEDINFO, | |
285 | i2d_OCSP_SERVICELOC, | |
286 | i2d_OCSP_SIGNATURE, | |
287 | i2d_OCSP_SINGLERESP, | |
8869ad4a AK |
288 | i2d_OSSL_CMP_MSG, |
289 | i2d_OSSL_CMP_PKIHEADER, | |
290 | i2d_OSSL_CRMF_CERTID, | |
291 | i2d_OSSL_CRMF_CERTTEMPLATE, | |
292 | i2d_OSSL_CRMF_ENCRYPTEDVALUE, | |
293 | i2d_OSSL_CRMF_MSG, | |
294 | i2d_OSSL_CRMF_MSGS, | |
295 | i2d_OSSL_CRMF_PBMPARAMETER, | |
296 | i2d_OSSL_CRMF_PKIPUBLICATIONINFO, | |
297 | i2d_OSSL_CRMF_SINGLEPUBINFO, | |
4692340e RS |
298 | i2d_OTHERNAME, |
299 | i2d_PBE2PARAM, | |
300 | i2d_PBEPARAM, | |
301 | i2d_PBKDF2PARAM, | |
302 | i2d_PKCS12, | |
303 | i2d_PKCS12_BAGS, | |
304 | i2d_PKCS12_MAC_DATA, | |
305 | i2d_PKCS12_SAFEBAG, | |
306 | i2d_PKCS12_bio, | |
307 | i2d_PKCS12_fp, | |
308 | i2d_PKCS7, | |
309 | i2d_PKCS7_DIGEST, | |
310 | i2d_PKCS7_ENCRYPT, | |
311 | i2d_PKCS7_ENC_CONTENT, | |
312 | i2d_PKCS7_ENVELOPE, | |
313 | i2d_PKCS7_ISSUER_AND_SERIAL, | |
314 | i2d_PKCS7_NDEF, | |
315 | i2d_PKCS7_RECIP_INFO, | |
316 | i2d_PKCS7_SIGNED, | |
317 | i2d_PKCS7_SIGNER_INFO, | |
318 | i2d_PKCS7_SIGN_ENVELOPE, | |
319 | i2d_PKCS7_bio, | |
320 | i2d_PKCS7_fp, | |
321 | i2d_PKCS8PrivateKeyInfo_bio, | |
322 | i2d_PKCS8PrivateKeyInfo_fp, | |
323 | i2d_PKCS8_PRIV_KEY_INFO, | |
324 | i2d_PKCS8_PRIV_KEY_INFO_bio, | |
325 | i2d_PKCS8_PRIV_KEY_INFO_fp, | |
326 | i2d_PKCS8_bio, | |
327 | i2d_PKCS8_fp, | |
328 | i2d_PKEY_USAGE_PERIOD, | |
329 | i2d_POLICYINFO, | |
330 | i2d_POLICYQUALINFO, | |
fa743582 | 331 | i2d_PROFESSION_INFO, |
4692340e RS |
332 | i2d_PROXY_CERT_INFO_EXTENSION, |
333 | i2d_PROXY_POLICY, | |
4692340e RS |
334 | i2d_RSAPrivateKey, |
335 | i2d_RSAPrivateKey_bio, | |
336 | i2d_RSAPrivateKey_fp, | |
337 | i2d_RSAPublicKey, | |
338 | i2d_RSAPublicKey_bio, | |
339 | i2d_RSAPublicKey_fp, | |
340 | i2d_RSA_OAEP_PARAMS, | |
341 | i2d_RSA_PSS_PARAMS, | |
342 | i2d_RSA_PUBKEY, | |
343 | i2d_RSA_PUBKEY_bio, | |
344 | i2d_RSA_PUBKEY_fp, | |
00606b06 | 345 | i2d_SCRYPT_PARAMS, |
4692340e RS |
346 | i2d_SCT_LIST, |
347 | i2d_SXNET, | |
348 | i2d_SXNETID, | |
349 | i2d_TS_ACCURACY, | |
350 | i2d_TS_MSG_IMPRINT, | |
351 | i2d_TS_MSG_IMPRINT_bio, | |
352 | i2d_TS_MSG_IMPRINT_fp, | |
353 | i2d_TS_REQ, | |
354 | i2d_TS_REQ_bio, | |
355 | i2d_TS_REQ_fp, | |
356 | i2d_TS_RESP, | |
357 | i2d_TS_RESP_bio, | |
358 | i2d_TS_RESP_fp, | |
359 | i2d_TS_STATUS_INFO, | |
360 | i2d_TS_TST_INFO, | |
361 | i2d_TS_TST_INFO_bio, | |
362 | i2d_TS_TST_INFO_fp, | |
363 | i2d_USERNOTICE, | |
364 | i2d_X509, | |
365 | i2d_X509_ALGOR, | |
366 | i2d_X509_ALGORS, | |
367 | i2d_X509_ATTRIBUTE, | |
368 | i2d_X509_CERT_AUX, | |
369 | i2d_X509_CINF, | |
370 | i2d_X509_CRL, | |
371 | i2d_X509_CRL_INFO, | |
372 | i2d_X509_CRL_bio, | |
373 | i2d_X509_CRL_fp, | |
374 | i2d_X509_EXTENSION, | |
375 | i2d_X509_EXTENSIONS, | |
376 | i2d_X509_NAME, | |
377 | i2d_X509_NAME_ENTRY, | |
378 | i2d_X509_PUBKEY, | |
379 | i2d_X509_REQ, | |
380 | i2d_X509_REQ_INFO, | |
381 | i2d_X509_REQ_bio, | |
382 | i2d_X509_REQ_fp, | |
383 | i2d_X509_REVOKED, | |
384 | i2d_X509_SIG, | |
385 | i2d_X509_VAL, | |
386 | - convert objects from/to ASN.1/DER representation | |
387 | ||
9946fceb DSH |
388 | =head1 SYNOPSIS |
389 | ||
bb82531f | 390 | =for openssl generic |
b97fdb57 | 391 | |
7c60a968 | 392 | TYPE *d2i_TYPE(TYPE **a, unsigned char **ppin, long length); |
4692340e RS |
393 | TYPE *d2i_TYPE_bio(BIO *bp, TYPE **a); |
394 | TYPE *d2i_TYPE_fp(FILE *fp, TYPE **a); | |
842d8e20 | 395 | |
9fdcc21f | 396 | int i2d_TYPE(const TYPE *a, unsigned char **ppout); |
7c60a968 | 397 | int i2d_TYPE(TYPE *a, unsigned char **ppout); |
9fdcc21f | 398 | int i2d_TYPE_fp(FILE *fp, const TYPE *a); |
4692340e | 399 | int i2d_TYPE_fp(FILE *fp, TYPE *a); |
9fdcc21f | 400 | int i2d_TYPE_bio(BIO *bp, const TYPE *a); |
4692340e | 401 | int i2d_TYPE_bio(BIO *bp, TYPE *a); |
9946fceb | 402 | |
4692340e | 403 | =head1 DESCRIPTION |
9946fceb | 404 | |
bbecf04e | 405 | In the description here, B<I<TYPE>> is used a placeholder |
4692340e | 406 | for any of the OpenSSL datatypes, such as I<X509_CRL>. |
7c60a968 DMSP |
407 | The function parameters I<ppin> and I<ppout> are generally |
408 | either both named I<pp> in the headers, or I<in> and I<out>. | |
95b1752c | 409 | |
4692340e RS |
410 | These functions convert OpenSSL objects to and from their ASN.1/DER |
411 | encoding. Unlike the C structures which can have pointers to sub-objects | |
412 | within, the DER is a serialized encoding, suitable for sending over the | |
413 | network, writing to a file, and so on. | |
9946fceb | 414 | |
bbecf04e RL |
415 | B<d2i_I<TYPE>>() attempts to decode I<len> bytes at I<*ppin>. If successful a |
416 | pointer to the B<I<TYPE>> structure is returned and I<*ppin> is incremented to | |
417 | the byte following the parsed data. If I<a> is not NULL then a pointer | |
418 | to the returned structure is also written to I<*a>. If an error occurred | |
419 | then NULL is returned. | |
9946fceb | 420 | |
bbecf04e RL |
421 | On a successful return, if I<*a> is not NULL then it is assumed that I<*a> |
422 | contains a valid B<I<TYPE>> structure and an attempt is made to reuse it. This | |
4692340e RS |
423 | "reuse" capability is present for historical compatibility but its use is |
424 | B<strongly discouraged> (see BUGS below, and the discussion in the RETURN | |
425 | VALUES section). | |
09f278f9 | 426 | |
bbecf04e RL |
427 | B<d2i_I<TYPE>_bio>() is similar to B<d2i_I<TYPE>>() except it attempts |
428 | to parse data from BIO I<bp>. | |
9946fceb | 429 | |
bbecf04e RL |
430 | B<d2i_I<TYPE>_fp>() is similar to B<d2i_I<TYPE>>() except it attempts |
431 | to parse data from FILE pointer I<fp>. | |
fde2257f | 432 | |
bbecf04e RL |
433 | B<i2d_I<TYPE>>() encodes the structure pointed to by I<a> into DER format. |
434 | If I<ppout> is not NULL, it writes the DER encoded data to the buffer | |
435 | at I<*ppout>, and increments it to point after the data just written. | |
9946fceb | 436 | If the return value is negative an error occurred, otherwise it |
1bc74519 | 437 | returns the length of the encoded data. |
9946fceb | 438 | |
bbecf04e RL |
439 | If I<*ppout> is NULL memory will be allocated for a buffer and the encoded |
440 | data written to it. In this case I<*ppout> is not incremented and it points | |
4692340e | 441 | to the start of the data just written. |
9946fceb | 442 | |
bbecf04e RL |
443 | B<i2d_I<TYPE>_bio>() is similar to B<i2d_I<TYPE>>() except it writes |
444 | the encoding of the structure I<a> to BIO I<bp> and it | |
cfae3d94 | 445 | returns 1 for success and 0 for failure. |
9946fceb | 446 | |
bbecf04e RL |
447 | B<i2d_I<TYPE>_fp>() is similar to B<i2d_I<TYPE>>() except it writes |
448 | the encoding of the structure I<a> to BIO I<bp> and it | |
cfae3d94 | 449 | returns 1 for success and 0 for failure. |
9946fceb | 450 | |
4692340e RS |
451 | These routines do not encrypt private keys and therefore offer no |
452 | security; use L<PEM_write_PrivateKey(3)> or similar for writing to files. | |
95b1752c | 453 | |
9946fceb DSH |
454 | =head1 NOTES |
455 | ||
bbecf04e | 456 | The letters B<i> and B<d> in B<i2d_I<TYPE>>() stand for |
4692340e | 457 | "internal" (that is, an internal C structure) and "DER" respectively. |
bbecf04e | 458 | So B<i2d_I<TYPE>>() converts from internal to DER. |
9946fceb DSH |
459 | |
460 | The functions can also understand B<BER> forms. | |
461 | ||
bbecf04e RL |
462 | The actual TYPE structure passed to B<i2d_I<TYPE>>() must be a valid |
463 | populated B<I<TYPE>> structure -- it B<cannot> simply be fed with an | |
4692340e | 464 | empty structure such as that returned by TYPE_new(). |
9946fceb | 465 | |
9c0586d5 | 466 | The encoded data is in binary form and may contain embedded zeros. |
9946fceb | 467 | Therefore any FILE pointers or BIOs should be opened in binary mode. |
35cb565a | 468 | Functions such as strlen() will B<not> return the correct length |
9946fceb DSH |
469 | of the encoded structure. |
470 | ||
bbecf04e | 471 | The ways that I<*ppin> and I<*ppout> are incremented after the operation |
9946fceb DSH |
472 | can trap the unwary. See the B<WARNINGS> section for some common |
473 | errors. | |
4692340e | 474 | The reason for this-auto increment behaviour is to reflect a typical |
12e0ea30 | 475 | usage of ASN1 functions: after one structure is encoded or decoded |
4692340e RS |
476 | another will be processed after it. |
477 | ||
478 | The following points about the data types might be useful: | |
479 | ||
e1271ac2 | 480 | =over 4 |
4692340e RS |
481 | |
482 | =item B<ASN1_OBJECT> | |
483 | ||
484 | Represents an ASN1 OBJECT IDENTIFIER. | |
485 | ||
486 | =item B<DHparams> | |
487 | ||
488 | Represents a PKCS#3 DH parameters structure. | |
489 | ||
490 | =item B<DHparamx> | |
491 | ||
3266cf58 | 492 | Represents an ANSI X9.42 DH parameters structure. |
4692340e RS |
493 | |
494 | =item B<DSA_PUBKEY> | |
495 | ||
496 | Represents a DSA public key using a B<SubjectPublicKeyInfo> structure. | |
497 | ||
bbecf04e | 498 | =item B<DSAPublicKey>, B<DSAPrivateKey> |
4692340e RS |
499 | |
500 | Use a non-standard OpenSSL format and should be avoided; use B<DSA_PUBKEY>, | |
bbecf04e | 501 | L<PEM_write_PrivateKey(3)>, or similar instead. |
4692340e | 502 | |
bbda7997 MC |
503 | =item B<ECDSA_SIG> |
504 | ||
505 | Represents an ECDSA signature. | |
506 | ||
4692340e RS |
507 | =item B<RSAPublicKey> |
508 | ||
509 | Represents a PKCS#1 RSA public key structure. | |
510 | ||
511 | =item B<X509_ALGOR> | |
512 | ||
27b138e9 | 513 | Represents an B<AlgorithmIdentifier> structure as used in IETF RFC 6960 and |
4692340e RS |
514 | elsewhere. |
515 | ||
516 | =item B<X509_Name> | |
517 | ||
518 | Represents a B<Name> type as used for subject and issuer names in | |
519 | IETF RFC 6960 and elsewhere. | |
520 | ||
521 | =item B<X509_REQ> | |
522 | ||
523 | Represents a PKCS#10 certificate request. | |
524 | ||
525 | =item B<X509_SIG> | |
526 | ||
527 | Represents the B<DigestInfo> structure defined in PKCS#1 and PKCS#7. | |
528 | ||
529 | =back | |
9946fceb | 530 | |
4564e77a PY |
531 | =head1 RETURN VALUES |
532 | ||
bbecf04e RL |
533 | B<d2i_I<TYPE>>(), B<d2i_I<TYPE>_bio>() and B<d2i_I<TYPE>_fp>() return a valid |
534 | B<I<TYPE>> structure or NULL if an error occurs. If the "reuse" capability has | |
535 | been used with a valid structure being passed in via I<a>, then the object is | |
536 | freed in the event of error and I<*a> is set to NULL. | |
4564e77a | 537 | |
bbecf04e | 538 | B<i2d_I<TYPE>>() returns the number of bytes successfully encoded or a negative |
4564e77a PY |
539 | value if an error occurs. |
540 | ||
bbecf04e RL |
541 | B<i2d_I<TYPE>_bio>() and B<i2d_I<TYPE>_fp>() return 1 for success and 0 if an |
542 | error occurs. | |
4564e77a | 543 | |
9946fceb DSH |
544 | =head1 EXAMPLES |
545 | ||
546 | Allocate and encode the DER encoding of an X509 structure: | |
547 | ||
9946fceb DSH |
548 | int len; |
549 | unsigned char *buf; | |
550 | ||
551 | buf = NULL; | |
9946fceb | 552 | len = i2d_X509(x, &buf); |
9946fceb | 553 | if (len < 0) |
4692340e | 554 | /* error */ |
9946fceb DSH |
555 | |
556 | Attempt to decode a buffer: | |
557 | ||
558 | X509 *x; | |
9946fceb | 559 | unsigned char *buf, *p; |
9946fceb DSH |
560 | int len; |
561 | ||
4692340e | 562 | /* Set up buf and len to point to the input buffer. */ |
9946fceb | 563 | p = buf; |
9946fceb | 564 | x = d2i_X509(NULL, &p, len); |
9946fceb | 565 | if (x == NULL) |
4692340e | 566 | /* error */ |
9946fceb DSH |
567 | |
568 | Alternative technique: | |
569 | ||
570 | X509 *x; | |
9946fceb | 571 | unsigned char *buf, *p; |
9946fceb DSH |
572 | int len; |
573 | ||
4692340e | 574 | /* Set up buf and len to point to the input buffer. */ |
9946fceb | 575 | p = buf; |
9946fceb DSH |
576 | x = NULL; |
577 | ||
4692340e RS |
578 | if (d2i_X509(&x, &p, len) == NULL) |
579 | /* error */ | |
9946fceb DSH |
580 | |
581 | =head1 WARNINGS | |
582 | ||
4692340e | 583 | Using a temporary variable is mandatory. A common |
9946fceb DSH |
584 | mistake is to attempt to use a buffer directly as follows: |
585 | ||
586 | int len; | |
587 | unsigned char *buf; | |
588 | ||
589 | len = i2d_X509(x, NULL); | |
9946fceb | 590 | buf = OPENSSL_malloc(len); |
4692340e | 591 | ... |
9946fceb | 592 | i2d_X509(x, &buf); |
4692340e | 593 | ... |
9946fceb DSH |
594 | OPENSSL_free(buf); |
595 | ||
bbecf04e | 596 | This code will result in I<buf> apparently containing garbage because |
9946fceb | 597 | it was incremented after the call to point after the data just written. |
bbecf04e | 598 | Also I<buf> will no longer contain the pointer allocated by OPENSSL_malloc() |
4692340e | 599 | and the subsequent call to OPENSSL_free() is likely to crash. |
9946fceb | 600 | |
bbecf04e | 601 | Another trap to avoid is misuse of the I<a> argument to B<d2i_I<TYPE>>(): |
9946fceb DSH |
602 | |
603 | X509 *x; | |
604 | ||
4692340e RS |
605 | if (d2i_X509(&x, &p, len) == NULL) |
606 | /* error */ | |
9946fceb | 607 | |
35cb565a | 608 | This will probably crash somewhere in d2i_X509(). The reason for this |
bbecf04e | 609 | is that the variable I<x> is uninitialized and an attempt will be made to |
9946fceb | 610 | interpret its (invalid) value as an B<X509> structure, typically causing |
bbecf04e | 611 | a segmentation violation. If I<x> is set to NULL first then this will not |
9946fceb DSH |
612 | happen. |
613 | ||
614 | =head1 BUGS | |
615 | ||
bbecf04e RL |
616 | In some versions of OpenSSL the "reuse" behaviour of B<d2i_I<TYPE>>() when |
617 | I<*a> is valid is broken and some parts of the reused structure may | |
b1d14c41 MC |
618 | persist if they are not present in the new one. Additionally, in versions of |
619 | OpenSSL prior to 1.1.0, when the "reuse" behaviour is used and an error occurs | |
620 | the behaviour is inconsistent. Some functions behaved as described here, while | |
bbecf04e | 621 | some did not free I<*a> on error and did not set I<*a> to NULL. |
b1d14c41 MC |
622 | |
623 | As a result of the above issues the "reuse" behaviour is strongly discouraged. | |
9946fceb | 624 | |
bbecf04e | 625 | B<i2d_I<TYPE>>() will not return an error in many versions of OpenSSL, |
9946fceb | 626 | if mandatory fields are not initialized due to a programming error |
12e0ea30 | 627 | then the encoded structure may contain invalid data or omit the |
bbecf04e RL |
628 | fields entirely and will not be parsed by B<d2i_I<TYPE>>(). This may be |
629 | fixed in future so code should not assume that B<i2d_I<TYPE>>() will | |
9946fceb DSH |
630 | always succeed. |
631 | ||
bbecf04e RL |
632 | Any function which encodes a structure (B<i2d_I<TYPE>>(), |
633 | B<i2d_I<TYPE>>() or B<i2d_I<TYPE>>()) may return a stale encoding if the | |
4692340e RS |
634 | structure has been modified after deserialization or previous |
635 | serialization. This is because some objects cache the encoding for | |
636 | efficiency reasons. | |
95b1752c | 637 | |
e2f92610 RS |
638 | =head1 COPYRIGHT |
639 | ||
6738bf14 | 640 | Copyright 1998-2018 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 641 | |
4746f25a | 642 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
643 | this file except in compliance with the License. You can obtain a copy |
644 | in the file LICENSE in the source distribution or at | |
645 | L<https://www.openssl.org/source/license.html>. | |
646 | ||
647 | =cut |