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