16c993574145a693b6d55892a469bd2428abb2dd
[openssl.git] / doc / man3 / X509_dup.pod
1 =pod
2
3 =head1 NAME
4
5 DECLARE_ASN1_FUNCTIONS,
6 IMPLEMENT_ASN1_FUNCTIONS,
7 ASN1_ITEM,
8 ACCESS_DESCRIPTION_free,
9 ACCESS_DESCRIPTION_new,
10 ADMISSIONS_free,
11 ADMISSIONS_new,
12 ADMISSION_SYNTAX_free,
13 ADMISSION_SYNTAX_new,
14 ASIdOrRange_free,
15 ASIdOrRange_new,
16 ASIdentifierChoice_free,
17 ASIdentifierChoice_new,
18 ASIdentifiers_free,
19 ASIdentifiers_new,
20 ASRange_free,
21 ASRange_new,
22 AUTHORITY_INFO_ACCESS_free,
23 AUTHORITY_INFO_ACCESS_new,
24 AUTHORITY_KEYID_free,
25 AUTHORITY_KEYID_new,
26 BASIC_CONSTRAINTS_free,
27 BASIC_CONSTRAINTS_new,
28 CERTIFICATEPOLICIES_free,
29 CERTIFICATEPOLICIES_new,
30 CMS_ContentInfo_free,
31 CMS_ContentInfo_new,
32 CMS_ContentInfo_print_ctx,
33 CMS_ReceiptRequest_free,
34 CMS_ReceiptRequest_new,
35 CRL_DIST_POINTS_free,
36 CRL_DIST_POINTS_new,
37 DIRECTORYSTRING_free,
38 DIRECTORYSTRING_new,
39 DISPLAYTEXT_free,
40 DISPLAYTEXT_new,
41 DIST_POINT_NAME_free,
42 DIST_POINT_NAME_new,
43 DIST_POINT_free,
44 DIST_POINT_new,
45 DSAparams_dup,
46 ECPARAMETERS_free,
47 ECPARAMETERS_new,
48 ECPKPARAMETERS_free,
49 ECPKPARAMETERS_new,
50 EDIPARTYNAME_free,
51 EDIPARTYNAME_new,
52 ESS_CERT_ID_dup,
53 ESS_CERT_ID_free,
54 ESS_CERT_ID_new,
55 ESS_CERT_ID_V2_dup,
56 ESS_CERT_ID_V2_free,
57 ESS_CERT_ID_V2_new,
58 ESS_ISSUER_SERIAL_dup,
59 ESS_ISSUER_SERIAL_free,
60 ESS_ISSUER_SERIAL_new,
61 ESS_SIGNING_CERT_dup,
62 ESS_SIGNING_CERT_free,
63 ESS_SIGNING_CERT_new,
64 ESS_SIGNING_CERT_V2_dup,
65 ESS_SIGNING_CERT_V2_free,
66 ESS_SIGNING_CERT_V2_new,
67 EXTENDED_KEY_USAGE_free,
68 EXTENDED_KEY_USAGE_new,
69 GENERAL_NAMES_free,
70 GENERAL_NAMES_new,
71 GENERAL_NAME_dup,
72 GENERAL_NAME_free,
73 GENERAL_NAME_new,
74 GENERAL_SUBTREE_free,
75 GENERAL_SUBTREE_new,
76 IPAddressChoice_free,
77 IPAddressChoice_new,
78 IPAddressFamily_free,
79 IPAddressFamily_new,
80 IPAddressOrRange_free,
81 IPAddressOrRange_new,
82 IPAddressRange_free,
83 IPAddressRange_new,
84 ISSUING_DIST_POINT_free,
85 ISSUING_DIST_POINT_new,
86 NAME_CONSTRAINTS_free,
87 NAME_CONSTRAINTS_new,
88 NAMING_AUTHORITY_free,
89 NAMING_AUTHORITY_new,
90 NETSCAPE_CERT_SEQUENCE_free,
91 NETSCAPE_CERT_SEQUENCE_new,
92 NETSCAPE_SPKAC_free,
93 NETSCAPE_SPKAC_new,
94 NETSCAPE_SPKI_free,
95 NETSCAPE_SPKI_new,
96 NOTICEREF_free,
97 NOTICEREF_new,
98 OCSP_BASICRESP_free,
99 OCSP_BASICRESP_new,
100 OCSP_CERTID_dup,
101 OCSP_CERTID_new,
102 OCSP_CERTSTATUS_free,
103 OCSP_CERTSTATUS_new,
104 OCSP_CRLID_free,
105 OCSP_CRLID_new,
106 OCSP_ONEREQ_free,
107 OCSP_ONEREQ_new,
108 OCSP_REQINFO_free,
109 OCSP_REQINFO_new,
110 OCSP_RESPBYTES_free,
111 OCSP_RESPBYTES_new,
112 OCSP_RESPDATA_free,
113 OCSP_RESPDATA_new,
114 OCSP_RESPID_free,
115 OCSP_RESPID_new,
116 OCSP_RESPONSE_new,
117 OCSP_REVOKEDINFO_free,
118 OCSP_REVOKEDINFO_new,
119 OCSP_SERVICELOC_free,
120 OCSP_SERVICELOC_new,
121 OCSP_SIGNATURE_free,
122 OCSP_SIGNATURE_new,
123 OCSP_SINGLERESP_free,
124 OCSP_SINGLERESP_new,
125 OSSL_CMP_ITAV_dup,
126 OSSL_CMP_ITAV_free,
127 OSSL_CMP_MSG_dup,
128 OSSL_CMP_MSG_it,
129 OSSL_CMP_MSG_free,
130 OSSL_CMP_PKIHEADER_free,
131 OSSL_CMP_PKIHEADER_it,
132 OSSL_CMP_PKIHEADER_new,
133 OSSL_CMP_PKISI_dup,
134 OSSL_CMP_PKISI_free,
135 OSSL_CMP_PKISI_it,
136 OSSL_CMP_PKISI_new,
137 OSSL_CMP_PKISTATUS_it,
138 OSSL_CRMF_CERTID_free,
139 OSSL_CRMF_CERTID_it,
140 OSSL_CRMF_CERTID_new,
141 OSSL_CRMF_CERTTEMPLATE_free,
142 OSSL_CRMF_CERTTEMPLATE_it,
143 OSSL_CRMF_CERTTEMPLATE_new,
144 OSSL_CRMF_ENCRYPTEDVALUE_free,
145 OSSL_CRMF_ENCRYPTEDVALUE_it,
146 OSSL_CRMF_ENCRYPTEDVALUE_new,
147 OSSL_CRMF_MSGS_free,
148 OSSL_CRMF_MSGS_it,
149 OSSL_CRMF_MSGS_new,
150 OSSL_CRMF_MSG_free,
151 OSSL_CRMF_MSG_it,
152 OSSL_CRMF_MSG_new,
153 OSSL_CRMF_PBMPARAMETER_free,
154 OSSL_CRMF_PBMPARAMETER_it,
155 OSSL_CRMF_PBMPARAMETER_new,
156 OSSL_CRMF_PKIPUBLICATIONINFO_free,
157 OSSL_CRMF_PKIPUBLICATIONINFO_it,
158 OSSL_CRMF_PKIPUBLICATIONINFO_new,
159 OSSL_CRMF_SINGLEPUBINFO_free,
160 OSSL_CRMF_SINGLEPUBINFO_it,
161 OSSL_CRMF_SINGLEPUBINFO_new,
162 OTHERNAME_free,
163 OTHERNAME_new,
164 PBE2PARAM_free,
165 PBE2PARAM_new,
166 PBEPARAM_free,
167 PBEPARAM_new,
168 PBKDF2PARAM_free,
169 PBKDF2PARAM_new,
170 PKCS12_BAGS_free,
171 PKCS12_BAGS_new,
172 PKCS12_MAC_DATA_free,
173 PKCS12_MAC_DATA_new,
174 PKCS12_SAFEBAG_free,
175 PKCS12_SAFEBAG_new,
176 PKCS12_free,
177 PKCS12_new,
178 PKCS7_DIGEST_free,
179 PKCS7_DIGEST_new,
180 PKCS7_ENCRYPT_free,
181 PKCS7_ENCRYPT_new,
182 PKCS7_ENC_CONTENT_free,
183 PKCS7_ENC_CONTENT_new,
184 PKCS7_ENVELOPE_free,
185 PKCS7_ENVELOPE_new,
186 PKCS7_ISSUER_AND_SERIAL_free,
187 PKCS7_ISSUER_AND_SERIAL_new,
188 PKCS7_RECIP_INFO_free,
189 PKCS7_RECIP_INFO_new,
190 PKCS7_SIGNED_free,
191 PKCS7_SIGNED_new,
192 PKCS7_SIGNER_INFO_free,
193 PKCS7_SIGNER_INFO_new,
194 PKCS7_SIGN_ENVELOPE_free,
195 PKCS7_SIGN_ENVELOPE_new,
196 PKCS7_dup,
197 PKCS7_free,
198 PKCS7_new,
199 PKCS7_print_ctx,
200 PKCS8_PRIV_KEY_INFO_free,
201 PKCS8_PRIV_KEY_INFO_new,
202 PKEY_USAGE_PERIOD_free,
203 PKEY_USAGE_PERIOD_new,
204 POLICYINFO_free,
205 POLICYINFO_new,
206 POLICYQUALINFO_free,
207 POLICYQUALINFO_new,
208 POLICY_CONSTRAINTS_free,
209 POLICY_CONSTRAINTS_new,
210 POLICY_MAPPING_free,
211 POLICY_MAPPING_new,
212 PROFESSION_INFOS_free,
213 PROFESSION_INFOS_new,
214 PROFESSION_INFO_free,
215 PROFESSION_INFO_new,
216 PROXY_CERT_INFO_EXTENSION_free,
217 PROXY_CERT_INFO_EXTENSION_new,
218 PROXY_POLICY_free,
219 PROXY_POLICY_new,
220 RSAPrivateKey_dup,
221 RSAPublicKey_dup,
222 RSA_OAEP_PARAMS_free,
223 RSA_OAEP_PARAMS_new,
224 RSA_PSS_PARAMS_free,
225 RSA_PSS_PARAMS_new,
226 SCRYPT_PARAMS_free,
227 SCRYPT_PARAMS_new,
228 SXNETID_free,
229 SXNETID_new,
230 SXNET_free,
231 SXNET_new,
232 TLS_FEATURE_free,
233 TLS_FEATURE_new,
234 TS_ACCURACY_dup,
235 TS_ACCURACY_free,
236 TS_ACCURACY_new,
237 TS_MSG_IMPRINT_dup,
238 TS_MSG_IMPRINT_free,
239 TS_MSG_IMPRINT_new,
240 TS_REQ_dup,
241 TS_REQ_free,
242 TS_REQ_new,
243 TS_RESP_dup,
244 TS_RESP_free,
245 TS_RESP_new,
246 TS_STATUS_INFO_dup,
247 TS_STATUS_INFO_free,
248 TS_STATUS_INFO_new,
249 TS_TST_INFO_dup,
250 TS_TST_INFO_free,
251 TS_TST_INFO_new,
252 USERNOTICE_free,
253 USERNOTICE_new,
254 X509_ALGOR_free,
255 X509_ALGOR_new,
256 X509_ATTRIBUTE_dup,
257 X509_ATTRIBUTE_free,
258 X509_ATTRIBUTE_new,
259 X509_CERT_AUX_free,
260 X509_CERT_AUX_new,
261 X509_CINF_free,
262 X509_CINF_new,
263 X509_CRL_INFO_free,
264 X509_CRL_INFO_new,
265 X509_CRL_dup,
266 X509_CRL_free,
267 X509_CRL_new,
268 X509_EXTENSION_dup,
269 X509_EXTENSION_free,
270 X509_EXTENSION_new,
271 X509_NAME_ENTRY_dup,
272 X509_NAME_ENTRY_free,
273 X509_NAME_ENTRY_new,
274 X509_NAME_dup,
275 X509_NAME_free,
276 X509_NAME_new,
277 X509_REQ_INFO_free,
278 X509_REQ_INFO_new,
279 X509_REQ_dup,
280 X509_REQ_free,
281 X509_REQ_new,
282 X509_REVOKED_dup,
283 X509_REVOKED_free,
284 X509_REVOKED_new,
285 X509_SIG_free,
286 X509_SIG_new,
287 X509_VAL_free,
288 X509_VAL_new,
289 X509_dup,
290 - ASN1 object utilities
291
292 =head1 SYNOPSIS
293
294 =for openssl generic
295
296  #include <openssl/asn1t.h>
297
298  DECLARE_ASN1_FUNCTIONS(type)
299  IMPLEMENT_ASN1_FUNCTIONS(stname)
300
301  typedef struct ASN1_ITEM_st ASN1_ITEM;
302
303  extern const ASN1_ITEM TYPE_it;
304  TYPE *TYPE_new(void);
305  TYPE *TYPE_dup(const TYPE *a);
306  void TYPE_free(TYPE *a);
307  int TYPE_print_ctx(BIO *out, TYPE *a, int indent, const ASN1_PCTX *pctx);
308
309 =head1 DESCRIPTION
310
311 In the description below, B<I<TYPE>> is used
312 as a placeholder for any of the OpenSSL datatypes, such as B<X509>.
313
314 The OpenSSL ASN1 parsing library templates are like a data-driven bytecode
315 interpreter.
316 Every ASN1 object as a global variable, TYPE_it, that describes the item
317 such as its fields.  (On systems which cannot export variables from shared
318 libraries, the global is instead a function which returns a pointer to a
319 static variable.
320
321 The macro DECLARE_ASN1_FUNCTIONS() is typically used in header files
322 to generate the function declarations.
323
324 The macro IMPLEMENT_ASN1_FUNCTIONS() is used once in a source file
325 to generate the function bodies.
326
327
328 B<I<TYPE>_new>() allocates an empty object of the indicated type.
329 The object returned must be released by calling B<I<TYPE>_free>().
330
331 B<I<TYPE>_dup>() copies an existing object, leaving it untouched.
332
333 B<I<TYPE>_free>() releases the object and all pointers and sub-objects
334 within it.
335
336 B<I<TYPE>_print_ctx>() prints the object I<a> on the specified BIO I<out>.
337 Each line will be prefixed with I<indent> spaces.
338 The I<pctx> specifies the printing context and is for internal
339 use; use NULL to get the default behavior.  If a print function is
340 user-defined, then pass in any I<pctx> down to any nested calls.
341
342 =head1 RETURN VALUES
343
344 B<I<TYPE>_new>() and B<I<TYPE>_dup>() return a pointer to the object or NULL on
345 failure.
346
347 B<I<TYPE>_print_ctx>() returns 1 on success or zero on failure.
348
349 =head1 COPYRIGHT
350
351 Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
352
353 Licensed under the Apache License 2.0 (the "License").  You may not use
354 this file except in compliance with the License.  You can obtain a copy
355 in the file LICENSE in the source distribution or at
356 L<https://www.openssl.org/source/license.html>.
357
358 =cut