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