secure/lib/libcrypto/man/man3/X509_get_extension_flags.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 "X509_GET_EXTENSION_FLAGS 3"
 136 .TH X509_GET_EXTENSION_FLAGS 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_subject_key_id, X509_get0_authority_key_id, X509_get0_authority_issuer, X509_get0_authority_serial, X509_get_pathlen, X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage, X509_set_proxy_flag, X509_set_proxy_pathlen, X509_get_proxy_pathlen \- retrieve certificate extension data
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/x509v3.h>
 147 \&
 148 \& long X509_get_pathlen(X509 *x);
 149 \& uint32_t X509_get_extension_flags(X509 *x);
 150 \& uint32_t X509_get_key_usage(X509 *x);
 151 \& uint32_t X509_get_extended_key_usage(X509 *x);
 152 \& const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
 153 \& const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x);
 154 \& const GENERAL_NAMES *X509_get0_authority_issuer(X509 *x);
 155 \& const ASN1_INTEGER *X509_get0_authority_serial(X509 *x);
 156 \& void X509_set_proxy_flag(X509 *x);
 157 \& void X509_set_proxy_pathlen(int l);
 158 \& long X509_get_proxy_pathlen(X509 *x);
 159 .Ve
 160 .SH "DESCRIPTION"
 161 .IX Header "DESCRIPTION"
 162 These functions retrieve information related to commonly used certificate extensions.
 163 .PP
 164 \&\fBX509_get_pathlen()\fR retrieves the path length extension from a certificate.
 165 This extension is used to limit the length of a cert chain that may be
 166 issued from that \s-1CA.\s0
 167 .PP
 168 \&\fBX509_get_extension_flags()\fR retrieves general information about a certificate,
 169 it will return one or more of the following flags ored together.
 170 .IP "\fB\s-1EXFLAG_V1\s0\fR" 4
 171 .IX Item "EXFLAG_V1"
 172 The certificate is an obsolete version 1 certificate.
 173 .IP "\fB\s-1EXFLAG_BCONS\s0\fR" 4
 174 .IX Item "EXFLAG_BCONS"
 175 The certificate contains a basic constraints extension.
 176 .IP "\fB\s-1EXFLAG_CA\s0\fR" 4
 177 .IX Item "EXFLAG_CA"
 178 The certificate contains basic constraints and asserts the \s-1CA\s0 flag.
 179 .IP "\fB\s-1EXFLAG_PROXY\s0\fR" 4
 180 .IX Item "EXFLAG_PROXY"
 181 The certificate is a valid proxy certificate.
 182 .IP "\fB\s-1EXFLAG_SI\s0\fR" 4
 183 .IX Item "EXFLAG_SI"
 184 The certificate is self issued (that is subject and issuer names match).
 185 .IP "\fB\s-1EXFLAG_SS\s0\fR" 4
 186 .IX Item "EXFLAG_SS"
 187 The subject and issuer names match and extension values imply it is self
 188 signed.
 189 .IP "\fB\s-1EXFLAG_FRESHEST\s0\fR" 4
 190 .IX Item "EXFLAG_FRESHEST"
 191 The freshest \s-1CRL\s0 extension is present in the certificate.
 192 .IP "\fB\s-1EXFLAG_CRITICAL\s0\fR" 4
 193 .IX Item "EXFLAG_CRITICAL"
 194 The certificate contains an unhandled critical extension.
 195 .IP "\fB\s-1EXFLAG_INVALID\s0\fR" 4
 196 .IX Item "EXFLAG_INVALID"
 197 Some certificate extension values are invalid or inconsistent.
 198 The certificate should be rejected.
 199 This bit may also be raised after an out-of-memory error while
 200 processing the X509 object, so it may not be related to the processed
 201 \&\s-1ASN1\s0 object itself.
 202 .IP "\fB\s-1EXFLAG_NO_FINGERPRINT\s0\fR" 4
 203 .IX Item "EXFLAG_NO_FINGERPRINT"
 204 Failed to compute the internal \s-1SHA1\s0 hash value of the certificate.
 205 This may be due to malloc failure or because no \s-1SHA1\s0 implementation was found.
 206 .IP "\fB\s-1EXFLAG_INVALID_POLICY\s0\fR" 4
 207 .IX Item "EXFLAG_INVALID_POLICY"
 208 The NID_certificate_policies certificate extension is invalid or
 209 inconsistent. The certificate should be rejected.
 210 This bit may also be raised after an out-of-memory error while
 211 processing the X509 object, so it may not be related to the processed
 212 \&\s-1ASN1\s0 object itself.
 213 .IP "\fB\s-1EXFLAG_KUSAGE\s0\fR" 4
 214 .IX Item "EXFLAG_KUSAGE"
 215 The certificate contains a key usage extension. The value can be retrieved
 216 using \fBX509_get_key_usage()\fR.
 217 .IP "\fB\s-1EXFLAG_XKUSAGE\s0\fR" 4
 218 .IX Item "EXFLAG_XKUSAGE"
 219 The certificate contains an extended key usage extension. The value can be
 220 retrieved using \fBX509_get_extended_key_usage()\fR.
 221 .PP
 222 \&\fBX509_get_key_usage()\fR returns the value of the key usage extension.  If key
 223 usage is present will return zero or more of the flags:
 224 \&\fB\s-1KU_DIGITAL_SIGNATURE\s0\fR, \fB\s-1KU_NON_REPUDIATION\s0\fR, \fB\s-1KU_KEY_ENCIPHERMENT\s0\fR,
 225 \&\fB\s-1KU_DATA_ENCIPHERMENT\s0\fR, \fB\s-1KU_KEY_AGREEMENT\s0\fR, \fB\s-1KU_KEY_CERT_SIGN\s0\fR,
 226 \&\fB\s-1KU_CRL_SIGN\s0\fR, \fB\s-1KU_ENCIPHER_ONLY\s0\fR or \fB\s-1KU_DECIPHER_ONLY\s0\fR corresponding to
 227 individual key usage bits. If key usage is absent then \fB\s-1UINT32_MAX\s0\fR is
 228 returned.
 229 .PP
 230 \&\fBX509_get_extended_key_usage()\fR returns the value of the extended key usage
 231 extension. If extended key usage is present it will return zero or more of the
 232 flags: \fB\s-1XKU_SSL_SERVER\s0\fR, \fB\s-1XKU_SSL_CLIENT\s0\fR, \fB\s-1XKU_SMIME\s0\fR, \fB\s-1XKU_CODE_SIGN\s0\fR
 233 \&\fB\s-1XKU_OCSP_SIGN\s0\fR, \fB\s-1XKU_TIMESTAMP\s0\fR, \fB\s-1XKU_DVCS\s0\fR or \fB\s-1XKU_ANYEKU\s0\fR. These
 234 correspond to the OIDs \fBid-kp-serverAuth\fR, \fBid-kp-clientAuth\fR,
 235 \&\fBid-kp-emailProtection\fR, \fBid-kp-codeSigning\fR, \fBid-kp-OCSPSigning\fR,
 236 \&\fBid-kp-timeStamping\fR, \fBid-kp-dvcs\fR and \fBanyExtendedKeyUsage\fR respectively.
 237 Additionally \fB\s-1XKU_SGC\s0\fR is set if either Netscape or Microsoft \s-1SGC\s0 OIDs are
 238 present.
 239 .PP
 240 \&\fBX509_get0_subject_key_id()\fR returns an internal pointer to the subject key
 241 identifier of \fBx\fR as an \fB\s-1ASN1_OCTET_STRING\s0\fR or \fB\s-1NULL\s0\fR if the extension
 242 is not present or cannot be parsed.
 243 .PP
 244 \&\fBX509_get0_authority_key_id()\fR returns an internal pointer to the authority key
 245 identifier of \fBx\fR as an \fB\s-1ASN1_OCTET_STRING\s0\fR or \fB\s-1NULL\s0\fR if the extension
 246 is not present or cannot be parsed.
 247 .PP
 248 \&\fBX509_get0_authority_issuer()\fR returns an internal pointer to the authority
 249 certificate issuer of \fBx\fR as a stack of \fB\s-1GENERAL_NAME\s0\fR structures or
 250 \&\fB\s-1NULL\s0\fR if the extension is not present or cannot be parsed.
 251 .PP
 252 \&\fBX509_get0_authority_serial()\fR returns an internal pointer to the authority
 253 certificate serial number of \fBx\fR as an \fB\s-1ASN1_INTEGER\s0\fR or \fB\s-1NULL\s0\fR if the
 254 extension is not present or cannot be parsed.
 255 .PP
 256 \&\fBX509_set_proxy_flag()\fR marks the certificate with the \fB\s-1EXFLAG_PROXY\s0\fR flag.
 257 This is for the users who need to mark non\-RFC3820 proxy certificates as
 258 such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 259 .PP
 260 \&\fBX509_set_proxy_pathlen()\fR sets the proxy certificate path length for the given
 261 certificate \fBx\fR.  This is for the users who need to mark non\-RFC3820 proxy
 262 certificates as such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 263 .PP
 264 \&\fBX509_get_proxy_pathlen()\fR returns the proxy certificate path length for the
 265 given certificate \fBx\fR if it is a proxy certificate.
 266 .SH "NOTES"
 267 .IX Header "NOTES"
 268 The value of the flags correspond to extension values which are cached
 269 in the \fBX509\fR structure. If the flags returned do not provide sufficient
 270 information an application should examine extension values directly
 271 for example using \fBX509_get_ext_d2i()\fR.
 272 .PP
 273 If the key usage or extended key usage extension is absent then typically usage
 274 is unrestricted. For this reason \fBX509_get_key_usage()\fR and
 275 \&\fBX509_get_extended_key_usage()\fR return \fB\s-1UINT32_MAX\s0\fR when the corresponding
 276 extension is absent. Applications can additionally check the return value of
 277 \&\fBX509_get_extension_flags()\fR and take appropriate action is an extension is
 278 absent.
 279 .PP
 280 If \fBX509_get0_subject_key_id()\fR returns \fB\s-1NULL\s0\fR then the extension may be
 281 absent or malformed. Applications can determine the precise reason using
 282 \&\fBX509_get_ext_d2i()\fR.
 283 .SH "RETURN VALUES"
 284 .IX Header "RETURN VALUES"
 285 \&\fBX509_get_pathlen()\fR returns the path length value, or \-1 if the extension
 286 is not present.
 287 .PP
 288 \&\fBX509_get_extension_flags()\fR, \fBX509_get_key_usage()\fR and
 289 \&\fBX509_get_extended_key_usage()\fR return sets of flags corresponding to the
 290 certificate extension values.
 291 .PP
 292 \&\fBX509_get0_subject_key_id()\fR returns the subject key identifier as a
 293 pointer to an \fB\s-1ASN1_OCTET_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if the extension
 294 is absent or an error occurred during parsing.
 295 .PP
 296 \&\fBX509_get_proxy_pathlen()\fR returns the path length value if the given
 297 certificate is a proxy one and has a path length set, and \-1 otherwise.
 298 .SH "SEE ALSO"
 299 .IX Header "SEE ALSO"
 300 \&\fBX509_check_purpose\fR\|(3)
 301 .SH "HISTORY"
 302 .IX Header "HISTORY"
 303 \&\fBX509_get_pathlen()\fR, \fBX509_set_proxy_flag()\fR, \fBX509_set_proxy_pathlen()\fR and
 304 \&\fBX509_get_proxy_pathlen()\fR were added in OpenSSL 1.1.0.
 305 .SH "COPYRIGHT"
 306 .IX Header "COPYRIGHT"
 307 Copyright 2015\-2021 The OpenSSL Project Authors. All Rights Reserved.
 308 .PP
 309 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 310 this file except in compliance with the License.  You can obtain a copy
 311 in the file \s-1LICENSE\s0 in the source distribution or at
 312 <https://www.openssl.org/source/license.html>.