secure/lib/libcrypto/man/man3/X509V3_get_d2i.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "X509V3_GET_D2I 3"
 136 .TH X509V3_GET_D2I 3 "2021-02-16" "1.1.1j" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 X509_get0_extensions, X509_CRL_get0_extensions, X509_REVOKED_get0_extensions, X509V3_get_d2i, X509V3_add1_i2d, X509V3_EXT_d2i, X509V3_EXT_i2d, X509_get_ext_d2i, X509_add1_ext_i2d, X509_CRL_get_ext_d2i, X509_CRL_add1_ext_i2d, X509_REVOKED_get_ext_d2i, X509_REVOKED_add1_ext_i2d \- X509 extension decode and encode functions
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509v3.h>
 147 \&
 148 \& void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
 149 \&                      int *idx);
 150 \& int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
 151 \&                     int crit, unsigned long flags);
 152 \&
 153 \& void *X509V3_EXT_d2i(X509_EXTENSION *ext);
 154 \& X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
 155 \&
 156 \& void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
 157 \& int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
 158 \&                       unsigned long flags);
 159 \&
 160 \& void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx);
 161 \& int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
 162 \&                           unsigned long flags);
 163 \&
 164 \& void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx);
 165 \& int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
 166 \&                               unsigned long flags);
 167 \&
 168 \& const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
 169 \& const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl);
 170 \& const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r);
 171 .Ve
 172 .SH "DESCRIPTION"
 173 .IX Header "DESCRIPTION"
 174 \&\fBX509V3_get_ext_d2i()\fR looks for an extension with \s-1OID\s0 \fBnid\fR in the extensions
 175 \&\fBx\fR and, if found, decodes it. If \fBidx\fR is \fB\s-1NULL\s0\fR then only one
 176 occurrence of an extension is permissible otherwise the first extension after
 177 index \fB*idx\fR is returned and \fB*idx\fR updated to the location of the extension.
 178 If \fBcrit\fR is not \fB\s-1NULL\s0\fR then \fB*crit\fR is set to a status value: \-2 if the
 179 extension occurs multiple times (this is only returned if \fBidx\fR is \fB\s-1NULL\s0\fR),
 180 \&\-1 if the extension could not be found, 0 if the extension is found and is
 181 not critical and 1 if critical. A pointer to an extension specific structure
 182 or \fB\s-1NULL\s0\fR is returned.
 183 .PP
 184 \&\fBX509V3_add1_i2d()\fR adds extension \fBvalue\fR to \s-1STACK\s0 \fB*x\fR (allocating a new
 185 \&\s-1STACK\s0 if necessary) using \s-1OID\s0 \fBnid\fR and criticality \fBcrit\fR according
 186 to \fBflags\fR.
 187 .PP
 188 \&\fBX509V3_EXT_d2i()\fR attempts to decode the \s-1ASN.1\s0 data contained in extension
 189 \&\fBext\fR and returns a pointer to an extension specific structure or \fB\s-1NULL\s0\fR
 190 if the extension could not be decoded (invalid syntax or not supported).
 191 .PP
 192 \&\fBX509V3_EXT_i2d()\fR encodes the extension specific structure \fBext\fR
 193 with \s-1OID\s0 \fBext_nid\fR and criticality \fBcrit\fR.
 194 .PP
 195 \&\fBX509_get_ext_d2i()\fR and \fBX509_add1_ext_i2d()\fR operate on the extensions of
 196 certificate \fBx\fR, they are otherwise identical to \fBX509V3_get_d2i()\fR and
 197 \&\fBX509V3_add_i2d()\fR.
 198 .PP
 199 \&\fBX509_CRL_get_ext_d2i()\fR and \fBX509_CRL_add1_ext_i2d()\fR operate on the extensions
 200 of \s-1CRL\s0 \fBcrl\fR, they are otherwise identical to \fBX509V3_get_d2i()\fR and
 201 \&\fBX509V3_add_i2d()\fR.
 202 .PP
 203 \&\fBX509_REVOKED_get_ext_d2i()\fR and \fBX509_REVOKED_add1_ext_i2d()\fR operate on the
 204 extensions of \fBX509_REVOKED\fR structure \fBr\fR (i.e for \s-1CRL\s0 entry extensions),
 205 they are otherwise identical to \fBX509V3_get_d2i()\fR and \fBX509V3_add_i2d()\fR.
 206 .PP
 207 \&\fBX509_get0_extensions()\fR, \fBX509_CRL_get0_extensions()\fR and
 208 \&\fBX509_REVOKED_get0_extensions()\fR return a stack of all the extensions
 209 of a certificate a \s-1CRL\s0 or a \s-1CRL\s0 entry respectively.
 210 .SH "NOTES"
 211 .IX Header "NOTES"
 212 In almost all cases an extension can occur at most once and multiple
 213 occurrences is an error. Therefore, the \fBidx\fR parameter is usually \fB\s-1NULL\s0\fR.
 214 .PP
 215 The \fBflags\fR parameter may be one of the following values.
 216 .PP
 217 \&\fBX509V3_ADD_DEFAULT\fR appends a new extension only if the extension does
 218 not already exist. An error is returned if the extension does already
 219 exist.
 220 .PP
 221 \&\fBX509V3_ADD_APPEND\fR appends a new extension, ignoring whether the extension
 222 already exists.
 223 .PP
 224 \&\fBX509V3_ADD_REPLACE\fR replaces an extension if it exists otherwise appends
 225 a new extension.
 226 .PP
 227 \&\fBX509V3_ADD_REPLACE_EXISTING\fR replaces an existing extension if it exists
 228 otherwise returns an error.
 229 .PP
 230 \&\fBX509V3_ADD_KEEP_EXISTING\fR appends a new extension only if the extension does
 231 not already exist. An error \fBis not\fR returned if the extension does already
 232 exist.
 233 .PP
 234 \&\fBX509V3_ADD_DELETE\fR extension \fBnid\fR is deleted: no new extension is added.
 235 .PP
 236 If \fBX509V3_ADD_SILENT\fR is ored with \fBflags\fR: any error returned will not
 237 be added to the error queue.
 238 .PP
 239 The function \fBX509V3_get_d2i()\fR will return \fB\s-1NULL\s0\fR if the extension is not
 240 found, occurs multiple times or cannot be decoded. It is possible to
 241 determine the precise reason by checking the value of \fB*crit\fR.
 242 .SH "SUPPORTED EXTENSIONS"
 243 .IX Header "SUPPORTED EXTENSIONS"
 244 The following sections contain a list of all supported extensions
 245 including their name and \s-1NID.\s0
 246 .SS "\s-1PKIX\s0 Certificate Extensions"
 247 .IX Subsection "PKIX Certificate Extensions"
 248 The following certificate extensions are defined in \s-1PKIX\s0 standards such as
 249 \&\s-1RFC5280.\s0
 250 .PP
 251 .Vb 3
 252 \& Basic Constraints                  NID_basic_constraints
 253 \& Key Usage                          NID_key_usage
 254 \& Extended Key Usage                 NID_ext_key_usage
 255 \&
 256 \& Subject Key Identifier             NID_subject_key_identifier
 257 \& Authority Key Identifier           NID_authority_key_identifier
 258 \&
 259 \& Private Key Usage Period           NID_private_key_usage_period
 260 \&
 261 \& Subject Alternative Name           NID_subject_alt_name
 262 \& Issuer Alternative Name            NID_issuer_alt_name
 263 \&
 264 \& Authority Information Access       NID_info_access
 265 \& Subject Information Access         NID_sinfo_access
 266 \&
 267 \& Name Constraints                   NID_name_constraints
 268 \&
 269 \& Certificate Policies               NID_certificate_policies
 270 \& Policy Mappings                    NID_policy_mappings
 271 \& Policy Constraints                 NID_policy_constraints
 272 \& Inhibit Any Policy                 NID_inhibit_any_policy
 273 \&
 274 \& TLS Feature                        NID_tlsfeature
 275 .Ve
 276 .SS "Netscape Certificate Extensions"
 277 .IX Subsection "Netscape Certificate Extensions"
 278 The following are (largely obsolete) Netscape certificate extensions.
 279 .PP
 280 .Vb 8
 281 \& Netscape Cert Type                 NID_netscape_cert_type
 282 \& Netscape Base Url                  NID_netscape_base_url
 283 \& Netscape Revocation Url            NID_netscape_revocation_url
 284 \& Netscape CA Revocation Url         NID_netscape_ca_revocation_url
 285 \& Netscape Renewal Url               NID_netscape_renewal_url
 286 \& Netscape CA Policy Url             NID_netscape_ca_policy_url
 287 \& Netscape SSL Server Name           NID_netscape_ssl_server_name
 288 \& Netscape Comment                   NID_netscape_comment
 289 .Ve
 290 .SS "Miscellaneous Certificate Extensions"
 291 .IX Subsection "Miscellaneous Certificate Extensions"
 292 .Vb 2
 293 \& Strong Extranet ID                 NID_sxnet
 294 \& Proxy Certificate Information      NID_proxyCertInfo
 295 .Ve
 296 .SS "\s-1PKIX CRL\s0 Extensions"
 297 .IX Subsection "PKIX CRL Extensions"
 298 The following are \s-1CRL\s0 extensions from \s-1PKIX\s0 standards such as \s-1RFC5280.\s0
 299 .PP
 300 .Vb 6
 301 \& CRL Number                         NID_crl_number
 302 \& CRL Distribution Points            NID_crl_distribution_points
 303 \& Delta CRL Indicator                NID_delta_crl
 304 \& Freshest CRL                       NID_freshest_crl
 305 \& Invalidity Date                    NID_invalidity_date
 306 \& Issuing Distribution Point         NID_issuing_distribution_point
 307 .Ve
 308 .PP
 309 The following are \s-1CRL\s0 entry extensions from \s-1PKIX\s0 standards such as \s-1RFC5280.\s0
 310 .PP
 311 .Vb 2
 312 \& CRL Reason Code                    NID_crl_reason
 313 \& Certificate Issuer                 NID_certificate_issuer
 314 .Ve
 315 .SS "\s-1OCSP\s0 Extensions"
 316 .IX Subsection "OCSP Extensions"
 317 .Vb 7
 318 \& OCSP Nonce                         NID_id_pkix_OCSP_Nonce
 319 \& OCSP CRL ID                        NID_id_pkix_OCSP_CrlID
 320 \& Acceptable OCSP Responses          NID_id_pkix_OCSP_acceptableResponses
 321 \& OCSP No Check                      NID_id_pkix_OCSP_noCheck
 322 \& OCSP Archive Cutoff                NID_id_pkix_OCSP_archiveCutoff
 323 \& OCSP Service Locator               NID_id_pkix_OCSP_serviceLocator
 324 \& Hold Instruction Code              NID_hold_instruction_code
 325 .Ve
 326 .SS "Certificate Transparency Extensions"
 327 .IX Subsection "Certificate Transparency Extensions"
 328 The following extensions are used by certificate transparency, \s-1RFC6962\s0
 329 .PP
 330 .Vb 2
 331 \& CT Precertificate SCTs             NID_ct_precert_scts
 332 \& CT Certificate SCTs                NID_ct_cert_scts
 333 .Ve
 334 .SH "RETURN VALUES"
 335 .IX Header "RETURN VALUES"
 336 \&\fBX509V3_EXT_d2i()\fR and *\fBX509V3_get_d2i()\fR return a pointer to an extension
 337 specific structure of \fB\s-1NULL\s0\fR if an error occurs.
 338 .PP
 339 \&\fBX509V3_EXT_i2d()\fR returns a pointer to an \fBX509_EXTENSION\fR structure
 340 or \fB\s-1NULL\s0\fR if an error occurs.
 341 .PP
 342 \&\fBX509V3_add1_i2d()\fR returns 1 if the operation is successful and 0 if it
 343 fails due to a non-fatal error (extension not found, already exists,
 344 cannot be encoded) or \-1 due to a fatal error such as a memory allocation
 345 failure.
 346 .PP
 347 \&\fBX509_get0_extensions()\fR, \fBX509_CRL_get0_extensions()\fR and
 348 \&\fBX509_REVOKED_get0_extensions()\fR return a stack of extensions. They return
 349 \&\s-1NULL\s0 if no extensions are present.
 350 .SH "SEE ALSO"
 351 .IX Header "SEE ALSO"
 352 \&\fBd2i_X509\fR\|(3),
 353 \&\fBERR_get_error\fR\|(3),
 354 \&\fBX509_CRL_get0_by_serial\fR\|(3),
 355 \&\fBX509_get0_signature\fR\|(3),
 356 \&\fBX509_get_ext_d2i\fR\|(3),
 357 \&\fBX509_get_extension_flags\fR\|(3),
 358 \&\fBX509_get_pubkey\fR\|(3),
 359 \&\fBX509_get_subject_name\fR\|(3),
 360 \&\fBX509_get_version\fR\|(3),
 361 \&\fBX509_NAME_add_entry_by_txt\fR\|(3),
 362 \&\fBX509_NAME_ENTRY_get_object\fR\|(3),
 363 \&\fBX509_NAME_get_index_by_NID\fR\|(3),
 364 \&\fBX509_NAME_print_ex\fR\|(3),
 365 \&\fBX509_new\fR\|(3),
 366 \&\fBX509_sign\fR\|(3),
 367 \&\fBX509_verify_cert\fR\|(3)
 368 .SH "COPYRIGHT"
 369 .IX Header "COPYRIGHT"
 370 Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
 371 .PP
 372 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 373 this file except in compliance with the License.  You can obtain a copy
 374 in the file \s-1LICENSE\s0 in the source distribution or at
 375 <https://www.openssl.org/source/license.html>.