secure/lib/libcrypto/man/X509V3_get_d2i.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   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 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "X509V3_GET_D2I 3"
 132 .TH X509V3_GET_D2I 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/x509v3.h>
 143 \&
 144 \& void *X509V3_get_d2i(const STACK_OF(X509_EXTENSION) *x, int nid, int *crit,
 145 \&                      int *idx);
 146 \& int X509V3_add1_i2d(STACK_OF(X509_EXTENSION) **x, int nid, void *value,
 147 \&                     int crit, unsigned long flags);
 148 \&
 149 \& void *X509V3_EXT_d2i(X509_EXTENSION *ext);
 150 \& X509_EXTENSION *X509V3_EXT_i2d(int ext_nid, int crit, void *ext);
 151 \&
 152 \& void *X509_get_ext_d2i(const X509 *x, int nid, int *crit, int *idx);
 153 \& int X509_add1_ext_i2d(X509 *x, int nid, void *value, int crit,
 154 \&                       unsigned long flags);
 155 \&
 156 \& void *X509_CRL_get_ext_d2i(const X509_CRL *crl, int nid, int *crit, int *idx);
 157 \& int X509_CRL_add1_ext_i2d(X509_CRL *crl, int nid, void *value, int crit,
 158 \&                           unsigned long flags);
 159 \&
 160 \& void *X509_REVOKED_get_ext_d2i(const X509_REVOKED *r, int nid, int *crit, int *idx);
 161 \& int X509_REVOKED_add1_ext_i2d(X509_REVOKED *r, int nid, void *value, int crit,
 162 \&                               unsigned long flags);
 163 \&
 164 \& const STACK_OF(X509_EXTENSION) *X509_get0_extensions(const X509 *x);
 165 \& const STACK_OF(X509_EXTENSION) *X509_CRL_get0_extensions(const X509_CRL *crl);
 166 \& const STACK_OF(X509_EXTENSION) *X509_REVOKED_get0_extensions(const X509_REVOKED *r);
 167 .Ve
 168 .SH "DESCRIPTION"
 169 .IX Header "DESCRIPTION"
 170 \&\fIX509V3_get_ext_d2i()\fR looks for an extension with \s-1OID\s0 \fBnid\fR in the extensions
 171 \&\fBx\fR and, if found, decodes it. If \fBidx\fR is \fB\s-1NULL\s0\fR then only one
 172 occurrence of an extension is permissible otherwise the first extension after
 173 index \fB*idx\fR is returned and \fB*idx\fR updated to the location of the extension.
 174 If \fBcrit\fR is not \fB\s-1NULL\s0\fR then \fB*crit\fR is set to a status value: \-2 if the
 175 extension occurs multiple times (this is only returned if \fBidx\fR is \fB\s-1NULL\s0\fR),
 176 \&\-1 if the extension could not be found, 0 if the extension is found and is
 177 not critical and 1 if critical. A pointer to an extension specific structure
 178 or \fB\s-1NULL\s0\fR is returned.
 179 .PP
 180 \&\fIX509V3_add1_i2d()\fR adds extension \fBvalue\fR to \s-1STACK\s0 \fB*x\fR (allocating a new
 181 \&\s-1STACK\s0 if necessary) using \s-1OID\s0 \fBnid\fR and criticality \fBcrit\fR according
 182 to \fBflags\fR.
 183 .PP
 184 \&\fIX509V3_EXT_d2i()\fR attempts to decode the \s-1ASN.1\s0 data contained in extension
 185 \&\fBext\fR and returns a pointer to an extension specific structure or \fB\s-1NULL\s0\fR
 186 if the extension could not be decoded (invalid syntax or not supported).
 187 .PP
 188 \&\fIX509V3_EXT_i2d()\fR encodes the extension specific structure \fBext\fR
 189 with \s-1OID\s0 \fBext_nid\fR and criticality \fBcrit\fR.
 190 .PP
 191 \&\fIX509_get_ext_d2i()\fR and \fIX509_add1_ext_i2d()\fR operate on the extensions of
 192 certificate \fBx\fR, they are otherwise identical to \fIX509V3_get_d2i()\fR and
 193 \&\fIX509V3_add_i2d()\fR.
 194 .PP
 195 \&\fIX509_CRL_get_ext_d2i()\fR and \fIX509_CRL_add1_ext_i2d()\fR operate on the extensions
 196 of \s-1CRL\s0 \fBcrl\fR, they are otherwise identical to \fIX509V3_get_d2i()\fR and
 197 \&\fIX509V3_add_i2d()\fR.
 198 .PP
 199 \&\fIX509_REVOKED_get_ext_d2i()\fR and \fIX509_REVOKED_add1_ext_i2d()\fR operate on the
 200 extensions of \fBX509_REVOKED\fR structure \fBr\fR (i.e for \s-1CRL\s0 entry extensions),
 201 they are otherwise identical to \fIX509V3_get_d2i()\fR and \fIX509V3_add_i2d()\fR.
 202 .PP
 203 \&\fIX509_get0_extensions()\fR, \fIX509_CRL_get0_extensions()\fR and
 204 \&\fIX509_REVOKED_get0_extensions()\fR return a stack of all the extensions
 205 of a certificate a \s-1CRL\s0 or a \s-1CRL\s0 entry respectively.
 206 .SH "NOTES"
 207 .IX Header "NOTES"
 208 In almost all cases an extension can occur at most once and multiple
 209 occurrences is an error. Therefore the \fBidx\fR parameter is usually \fB\s-1NULL\s0\fR.
 210 .PP
 211 The \fBflags\fR parameter may be one of the following values.
 212 .PP
 213 \&\fBX509V3_ADD_DEFAULT\fR appends a new extension only if the extension does
 214 not already exist. An error is returned if the extension does already
 215 exist.
 216 .PP
 217 \&\fBX509V3_ADD_APPEND\fR appends a new extension, ignoring whether the extension
 218 already exists.
 219 .PP
 220 \&\fBX509V3_ADD_REPLACE\fR replaces an extension if it exists otherwise appends
 221 a new extension.
 222 .PP
 223 \&\fBX509V3_ADD_REPLACE_EXISTING\fR replaces an existing extension if it exists
 224 otherwise returns an error.
 225 .PP
 226 \&\fBX509V3_ADD_KEEP_EXISTING\fR appends a new extension only if the extension does
 227 not already exist. An error \fBis not\fR returned if the extension does already
 228 exist.
 229 .PP
 230 \&\fBX509V3_ADD_DELETE\fR extension \fBnid\fR is deleted: no new extension is added.
 231 .PP
 232 If \fBX509V3_ADD_SILENT\fR is ored with \fBflags\fR: any error returned will not
 233 be added to the error queue.
 234 .PP
 235 The function \fIX509V3_get_d2i()\fR will return \fB\s-1NULL\s0\fR if the extension is not
 236 found, occurs multiple times or cannot be decoded. It is possible to
 237 determine the precise reason by checking the value of \fB*crit\fR.
 238 .SH "SUPPORTED EXTENSIONS"
 239 .IX Header "SUPPORTED EXTENSIONS"
 240 The following sections contain a list of all supported extensions
 241 including their name and \s-1NID.\s0
 242 .SS "\s-1PKIX\s0 Certificate Extensions"
 243 .IX Subsection "PKIX Certificate Extensions"
 244 The following certificate extensions are defined in \s-1PKIX\s0 standards such as
 245 \&\s-1RFC5280.\s0
 246 .PP
 247 .Vb 3
 248 \& Basic Constraints                  NID_basic_constraints
 249 \& Key Usage                          NID_key_usage
 250 \& Extended Key Usage                 NID_ext_key_usage
 251 \&
 252 \& Subject Key Identifier             NID_subject_key_identifier
 253 \& Authority Key Identifier           NID_authority_key_identifier
 254 \&
 255 \& Private Key Usage Period           NID_private_key_usage_period
 256 \&
 257 \& Subject Alternative Name           NID_subject_alt_name
 258 \& Issuer Alternative Name            NID_issuer_alt_name
 259 \&
 260 \& Authority Information Access       NID_info_access
 261 \& Subject Information Access         NID_sinfo_access
 262 \&
 263 \& Name Constraints                   NID_name_constraints
 264 \&
 265 \& Certificate Policies               NID_certificate_policies
 266 \& Policy Mappings                    NID_policy_mappings
 267 \& Policy Constraints                 NID_policy_constraints
 268 \& Inhibit Any Policy                 NID_inhibit_any_policy
 269 \&
 270 \& TLS Feature                        NID_tlsfeature
 271 .Ve
 272 .SS "Netscape Certificate Extensions"
 273 .IX Subsection "Netscape Certificate Extensions"
 274 The following are (largely obsolete) Netscape certificate extensions.
 275 .PP
 276 .Vb 8
 277 \& Netscape Cert Type                 NID_netscape_cert_type
 278 \& Netscape Base Url                  NID_netscape_base_url
 279 \& Netscape Revocation Url            NID_netscape_revocation_url
 280 \& Netscape CA Revocation Url         NID_netscape_ca_revocation_url
 281 \& Netscape Renewal Url               NID_netscape_renewal_url
 282 \& Netscape CA Policy Url             NID_netscape_ca_policy_url
 283 \& Netscape SSL Server Name           NID_netscape_ssl_server_name
 284 \& Netscape Comment                   NID_netscape_comment
 285 .Ve
 286 .SS "Miscellaneous Certificate Extensions"
 287 .IX Subsection "Miscellaneous Certificate Extensions"
 288 .Vb 2
 289 \& Strong Extranet ID                 NID_sxnet
 290 \& Proxy Certificate Information      NID_proxyCertInfo
 291 .Ve
 292 .SS "\s-1PKIX CRL\s0 Extensions"
 293 .IX Subsection "PKIX CRL Extensions"
 294 The following are \s-1CRL\s0 extensions from \s-1PKIX\s0 standards such as \s-1RFC5280.\s0
 295 .PP
 296 .Vb 6
 297 \& CRL Number                         NID_crl_number
 298 \& CRL Distribution Points            NID_crl_distribution_points
 299 \& Delta CRL Indicator                NID_delta_crl
 300 \& Freshest CRL                       NID_freshest_crl
 301 \& Invalidity Date                    NID_invalidity_date
 302 \& Issuing Distribution Point         NID_issuing_distribution_point
 303 .Ve
 304 .PP
 305 The following are \s-1CRL\s0 entry extensions from \s-1PKIX\s0 standards such as \s-1RFC5280.\s0
 306 .PP
 307 .Vb 2
 308 \& CRL Reason Code                    NID_crl_reason
 309 \& Certificate Issuer                 NID_certificate_issuer
 310 .Ve
 311 .SS "\s-1OCSP\s0 Extensions"
 312 .IX Subsection "OCSP Extensions"
 313 .Vb 7
 314 \& OCSP Nonce                         NID_id_pkix_OCSP_Nonce
 315 \& OCSP CRL ID                        NID_id_pkix_OCSP_CrlID
 316 \& Acceptable OCSP Responses          NID_id_pkix_OCSP_acceptableResponses
 317 \& OCSP No Check                      NID_id_pkix_OCSP_noCheck
 318 \& OCSP Archive Cutoff                NID_id_pkix_OCSP_archiveCutoff
 319 \& OCSP Service Locator               NID_id_pkix_OCSP_serviceLocator
 320 \& Hold Instruction Code              NID_hold_instruction_code
 321 .Ve
 322 .SS "Certificate Transparency Extensions"
 323 .IX Subsection "Certificate Transparency Extensions"
 324 The following extensions are used by certificate transparency, \s-1RFC6962\s0
 325 .PP
 326 .Vb 2
 327 \& CT Precertificate SCTs             NID_ct_precert_scts
 328 \& CT Certificate SCTs                NID_ct_cert_scts
 329 .Ve
 330 .SH "RETURN VALUES"
 331 .IX Header "RETURN VALUES"
 332 \&\fIX509V3_EXT_d2i()\fR and *\fIX509V3_get_d2i()\fR return a pointer to an extension
 333 specific structure of \fB\s-1NULL\s0\fR if an error occurs.
 334 .PP
 335 \&\fIX509V3_EXT_i2d()\fR returns a pointer to an \fBX509_EXTENSION\fR structure
 336 or \fB\s-1NULL\s0\fR if an error occurs.
 337 .PP
 338 \&\fIX509V3_add1_i2d()\fR returns 1 if the operation is successful and 0 if it
 339 fails due to a non-fatal error (extension not found, already exists,
 340 cannot be encoded) or \-1 due to a fatal error such as a memory allocation
 341 failure.
 342 .PP
 343 \&\fIX509_get0_extensions()\fR, \fIX509_CRL_get0_extensions()\fR and
 344 \&\fIX509_REVOKED_get0_extensions()\fR return a stack of extensions. They return
 345 \&\s-1NULL\s0 if no extensions are present.
 346 .SH "SEE ALSO"
 347 .IX Header "SEE ALSO"
 348 \&\fId2i_X509\fR\|(3),
 349 \&\fIERR_get_error\fR\|(3),
 350 \&\fIX509_CRL_get0_by_serial\fR\|(3),
 351 \&\fIX509_get0_signature\fR\|(3),
 352 \&\fIX509_get_ext_d2i\fR\|(3),
 353 \&\fIX509_get_extension_flags\fR\|(3),
 354 \&\fIX509_get_pubkey\fR\|(3),
 355 \&\fIX509_get_subject_name\fR\|(3),
 356 \&\fIX509_get_version\fR\|(3),
 357 \&\fIX509_NAME_add_entry_by_txt\fR\|(3),
 358 \&\fIX509_NAME_ENTRY_get_object\fR\|(3),
 359 \&\fIX509_NAME_get_index_by_NID\fR\|(3),
 360 \&\fIX509_NAME_print_ex\fR\|(3),
 361 \&\fIX509_new\fR\|(3),
 362 \&\fIX509_sign\fR\|(3),
 363 \&\fIX509_verify_cert\fR\|(3)
 364 .SH "COPYRIGHT"
 365 .IX Header "COPYRIGHT"
 366 Copyright 2015\-2016 The OpenSSL Project Authors. All Rights Reserved.
 367 .PP
 368 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 369 this file except in compliance with the License.  You can obtain a copy
 370 in the file \s-1LICENSE\s0 in the source distribution or at
 371 <https://www.openssl.org/source/license.html>.