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