doc/crypto/X509V3_get_d2i.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d,
   6 X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i,
   7 X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i,
   8 X509_REVOKED_add1_ext_i2d - X509 extension decode and encode functions
   9
  10 =head1 SYNOPSIS
  11
  12  #include <openssl/x509v3.h>
  13
  14  void *X509V3_get_d2i(STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
  15                       int *idx);
  16  int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
  17                      int crit, unsigned long flags);
  18
  19  void *X509V3_EXT_d2i(X509_EXTENSION *ext);
  20  X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
  21
  22  void *X509_get_ext_d2i(X509 *x, int nid, int *crit, int *idx);
  23  int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
  24                        unsigned long flags);
  25
  26  void *X509_CRL_get_ext_d2i(X509_CRL *crl, int nid, int *crit, int *idx);
  27  int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
  28                            unsigned long flags);
  29
  30  void *X509_REVOKED_get_ext_d2i(X509_REVOKED *r, int nid, int *crit, int *idx);
  31  int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
  32                                unsigned long flags);
  33
  34  STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
  35  STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(X509_CRL *crl);
  36  STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(X509_REVOKED *r);
  37
  38 =head1 DESCRIPTION
  39
  40 X509V3_get_ext_d2i() looks for an extension with OID B<nid> in the extensions
  41 B<x> and, if found, decodes it. If B<idx> is B<NULL> then only one
  42 occurrence of an extension is permissible otherwise the first extension after
  43 index B<*idx> is returned and B<*idx> updated to the location of the extension.
  44 If B<crit> is not B<NULL> then B<*crit> is set to a status value: -2 if the
  45 extension occurs multiple times (this is only returned if B<idx> is B<NULL>),
  46 -1 if the extension could not be found, 0 if the extension is found and is
  47 not critical and 1 if critical. A pointer to an extension specific structure
  48 or B<NULL> is returned.
  49
  50 X509V3_add1_i2d() adds extension B<value> to STACK B<*x> (allocating a new
  51 STACK if necessary) using OID B<nid> and criticality B<crit> according
  52 to B<flags>.
  53
  54 X509V3_EXT_d2i() attempts to decode the ASN.1 data contained in extension
  55 B<ext> and returns a pointer to an extension specific structure or B<NULL>
  56 if the extension could not be decoded (invalid syntax or not supported).
  57
  58 X509V3_EXT_i2d() encodes the extension specific structure B<ext>
  59 with OID B<ext_nid> and criticality B<crit>.
  60
  61 X509_get_ext_d2i() and X509_add1_ext_i2d() operate on the extensions of
  62 certificate B<x>, they are otherwise identical to X509V3_get_d2i() and
  63 X509V3_add_i2d().
  64
  65 X509_CRL_get_ext_d2i() and X509_CRL_add1_ext_i2d() operate on the extensions
  66 of CRL B<crl>, they are otherwise identical to X509V3_get_d2i() and
  67 X509V3_add_i2d().
  68
  69 X509_REVOKED_get_ext_d2i() and X509_REVOKED_add1_ext_i2d() operate on the
  70 extensions of B<X509_REVOKED> structure B<r> (i.e for CRL entry extensions),
  71 they are otherwise identical to X509V3_get_d2i() and X509V3_add_i2d().
  72
  73 X509_get0_extensions(), X509_CRL_get0_extensions() and
  74 X509_REVOKED_get0_extensions() return a stack of all the extensions
  75 of a certificate a CRL or a CRL entry respectively.
  76
  77 =head1 NOTES
  78
  79 In almost all cases an extension can occur at most once and multiple
  80 occurrences is an error. Therefore the B<idx> parameter is usually B<NULL>.
  81
  82 The B<flags> parameter may be one of the following values.
  83
  84 B<X509V3_ADD_DEFAULT> appends a new extension only if the extension does
  85 not already exist. An error is returned if the extension does already
  86 exist.
  87
  88 B<X509V3_ADD_APPEND> appends a new extension, ignoring whether the extension
  89 already exists.
  90
  91 B<X509V3_ADD_REPLACE> replaces an extension if it exists otherwise apppends
  92 a new extension.
  93
  94 B<X509V3_ADD_REPLACE_EXISTING> replaces an existing extension if it exists
  95 otherwise returns an error.
  96
  97 B<X509V3_ADD_KEEP_EXISTING> appends a new extension only if the extension does
  98 not already exist. An error B<is not> returned if the extension does already
  99 exist.
 100
 101 B<X509V3_ADD_DELETE> extension B<nid> is deleted: no new extenion is added.
 102
 103 If B<X509V3_ADD_SILENT> is ored with B<flags>: any error returned will not
 104 be added to the error queue.
 105
 106 The function X509V3_get_d2i() will return B<NULL> if the extension is not
 107 found, occurs multiple times or cannot be decoded. It is possible to
 108 determine the precise reason by checking the value of B<*crit>.
 109
 110 =head1 SUPPORTED EXTENSIONS
 111
 112 The following sections contain a list of all supported extensions
 113 including their name and NID.
 114
 115 =head2 PKIX CERTIFICATE EXTENSIONS
 116
 117 The following certificate extensions are defined in PKIX standards such as
 118 RFC5280.
 119
 120  Basic Constraints                  NID_basic_constraints
 121  Key Usage                          NID_key_usage
 122  Extended Key Usage                 NID_ext_key_usage
 123
 124  Subject Key Identifier             NID_subject_key_identifier
 125  Authority Key Identifier           NID_authority_key_identifier
 126
 127  Private Key Usage Period           NID_private_key_usage_period
 128
 129  Subject Alternative Name           NID_subject_alt_name
 130  Issuer Alternative Name            NID_issuer_alt_name
 131
 132  Authority Information Access       NID_info_access
 133  Subject Information Access         NID_sinfo_access
 134
 135  Name Constraints                   NID_name_constraints
 136
 137  Certificate Policies               NID_certificate_policies
 138  Policy Mappings                    NID_policy_mappings
 139  Policy Constraints                 NID_policy_constraints
 140  Inhibit Any Policy                 NID_inhibit_any_policy
 141
 142  TLS Feature                        NID_tlsfeature
 143
 144 =head2 NETSCAPE CERTIFICATE EXTENSIONS
 145
 146 The following are (largely obsolete) Netscape certificate extensions.
 147
 148  Netscape Cert Type                 NID_netscape_cert_type
 149  Netscape Base Url                  NID_netscape_base_url
 150  Netscape Revocation Url            NID_netscape_revocation_url
 151  Netscape CA Revocation Url         NID_netscape_ca_revocation_url
 152  Netscape Renewal Url               NID_netscape_renewal_url
 153  Netscape CA Policy Url             NID_netscape_ca_policy_url
 154  Netscape SSL Server Name           NID_netscape_ssl_server_name
 155  Netscape Comment                   NID_netscape_comment
 156
 157 =head2 MISCELLANEOUS CERTIFICATE EXTENSIONS
 158
 159  Strong Extranet ID                 NID_sxnet
 160  Proxy Certificate Information      NID_proxyCertInfo
 161
 162 =head2 PKIX CRL EXTENSIONS
 163
 164 The following are CRL extensions from PKIX standards such as RFC5280.
 165
 166  CRL Number                         NID_crl_number
 167  CRL Distribution Points            NID_crl_distribution_points
 168  Delta CRL Indicator                NID_delta_crl
 169  Freshest CRL                       NID_freshest_crl
 170  Invalidity Date                    NID_invalidity_date
 171  Issuing Distribution Point         NID_issuing_distribution_point
 172
 173 The following are CRL entry extensions from PKIX standards such as RFC5280.
 174
 175  CRL Reason Code                    NID_crl_reason
 176  Certificate Issuer                 NID_certificate_issuer
 177
 178 =head2 OCSP EXTENSIONS
 179
 180  OCSP Nonce                         NID_id_pkix_OCSP_Nonce
 181  OCSP CRL ID                        NID_id_pkix_OCSP_CrlID
 182  Acceptable OCSP Responses          NID_id_pkix_OCSP_acceptableResponses
 183  OCSP No Check                      NID_id_pkix_OCSP_noCheck
 184  OCSP Archive Cutoff                NID_id_pkix_OCSP_archiveCutoff
 185  OCSP Service Locator               NID_id_pkix_OCSP_serviceLocator
 186  Hold Instruction Code              NID_hold_instruction_code
 187
 188 =head2 CERTIFICATE TRANSPARENCY EXTENSIONS
 189
 190 The following extensions are used by certificate transparency, RFC6962
 191
 192  CT Precertificate SCTs             NID_ct_precert_scts
 193  CT Certificate SCTs                NID_ct_cert_scts
 194
 195 =head1 RETURN VALUES
 196
 197 X509V3_EXT_d2i() and *X509V3_get_d2i() return a pointer to an extension
 198 specific structure of B<NULL> if an error occurs.
 199
 200 X509V3_EXT_i2d() returns a pointer to an B<X509_EXTENSION> structure
 201 or B<NULL> if an error occurs.
 202
 203 X509V3_add1_i2d() returns 1 if the operation is successful and 0 if it
 204 fails due to a non-fatal error (extension not found, already exists,
 205 cannot be encoded) or -1 due to a fatal error such as a memory allocation
 206 failure.
 207
 208 X509_get0_extensions(), X509_CRL_get0_extensions() and
 209 X509_REVOKED_get0_extensions() return a stack of extensions. They can return
 210 NULL if no extensions are present.
 211
 212 =head1 SEE ALSO
 213
 214 L<d2i_X509(3)>,
 215 L<ERR_get_error(3)>,
 216 L<X509_CRL_get0_by_serial(3)>,
 217 L<X509_get0_signature(3)>,
 218 L<X509_get_ext_d2i(3)>,
 219 L<X509_get_extension_flags(3)>,
 220 L<X509_get_pubkey(3)>,
 221 L<X509_get_subject_name(3)>,
 222 L<X509_get_version(3)>,
 223 L<X509_NAME_add_entry_by_txt(3)>,
 224 L<X509_NAME_ENTRY_get_object(3)>,
 225 L<X509_NAME_get_index_by_NID(3)>,
 226 L<X509_NAME_print_ex(3)>,
 227 L<X509_new(3)>,
 228 L<X509_sign(3)>,
 229 L<X509_verify_cert(3)>
 230
 231 =cut