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