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

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.40)
   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 "2020-03-31" "1.1.1f" "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. The
 198 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_INVALID_POLICY\s0\fR" 4
 203 .IX Item "EXFLAG_INVALID_POLICY"
 204 The NID_certificate_policies certificate extension is invalid or
 205 inconsistent. The certificate should be rejected.
 206 This bit may also be raised after an out-of-memory error while
 207 processing the X509 object, so it may not be related to the processed
 208 \&\s-1ASN1\s0 object itself.
 209 .IP "\fB\s-1EXFLAG_KUSAGE\s0\fR" 4
 210 .IX Item "EXFLAG_KUSAGE"
 211 The certificate contains a key usage extension. The value can be retrieved
 212 using \fBX509_get_key_usage()\fR.
 213 .IP "\fB\s-1EXFLAG_XKUSAGE\s0\fR" 4
 214 .IX Item "EXFLAG_XKUSAGE"
 215 The certificate contains an extended key usage extension. The value can be
 216 retrieved using \fBX509_get_extended_key_usage()\fR.
 217 .PP
 218 \&\fBX509_get_key_usage()\fR returns the value of the key usage extension.  If key
 219 usage is present will return zero or more of the flags:
 220 \&\fB\s-1KU_DIGITAL_SIGNATURE\s0\fR, \fB\s-1KU_NON_REPUDIATION\s0\fR, \fB\s-1KU_KEY_ENCIPHERMENT\s0\fR,
 221 \&\fB\s-1KU_DATA_ENCIPHERMENT\s0\fR, \fB\s-1KU_KEY_AGREEMENT\s0\fR, \fB\s-1KU_KEY_CERT_SIGN\s0\fR,
 222 \&\fB\s-1KU_CRL_SIGN\s0\fR, \fB\s-1KU_ENCIPHER_ONLY\s0\fR or \fB\s-1KU_DECIPHER_ONLY\s0\fR corresponding to
 223 individual key usage bits. If key usage is absent then \fB\s-1UINT32_MAX\s0\fR is
 224 returned.
 225 .PP
 226 \&\fBX509_get_extended_key_usage()\fR returns the value of the extended key usage
 227 extension. If extended key usage is present it will return zero or more of the
 228 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
 229 \&\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
 230 correspond to the OIDs \fBid-kp-serverAuth\fR, \fBid-kp-clientAuth\fR,
 231 \&\fBid-kp-emailProtection\fR, \fBid-kp-codeSigning\fR, \fBid-kp-OCSPSigning\fR,
 232 \&\fBid-kp-timeStamping\fR, \fBid-kp-dvcs\fR and \fBanyExtendedKeyUsage\fR respectively.
 233 Additionally \fB\s-1XKU_SGC\s0\fR is set if either Netscape or Microsoft \s-1SGC\s0 OIDs are
 234 present.
 235 .PP
 236 \&\fBX509_get0_subject_key_id()\fR returns an internal pointer to the subject key
 237 identifier of \fBx\fR as an \fB\s-1ASN1_OCTET_STRING\s0\fR or \fB\s-1NULL\s0\fR if the extension
 238 is not present or cannot be parsed.
 239 .PP
 240 \&\fBX509_get0_authority_key_id()\fR returns an internal pointer to the authority 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_issuer()\fR returns an internal pointer to the authority
 245 certificate issuer of \fBx\fR as a stack of \fB\s-1GENERAL_NAME\s0\fR structures or
 246 \&\fB\s-1NULL\s0\fR if the extension is not present or cannot be parsed.
 247 .PP
 248 \&\fBX509_get0_authority_serial()\fR returns an internal pointer to the authority
 249 certificate serial number of \fBx\fR as an \fB\s-1ASN1_INTEGER\s0\fR or \fB\s-1NULL\s0\fR if the
 250 extension is not present or cannot be parsed.
 251 .PP
 252 \&\fBX509_set_proxy_flag()\fR marks the certificate with the \fB\s-1EXFLAG_PROXY\s0\fR flag.
 253 This is for the users who need to mark non\-RFC3820 proxy certificates as
 254 such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 255 .PP
 256 \&\fBX509_set_proxy_pathlen()\fR sets the proxy certificate path length for the given
 257 certificate \fBx\fR.  This is for the users who need to mark non\-RFC3820 proxy
 258 certificates as such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 259 .PP
 260 \&\fBX509_get_proxy_pathlen()\fR returns the proxy certificate path length for the
 261 given certificate \fBx\fR if it is a proxy certificate.
 262 .SH "NOTES"
 263 .IX Header "NOTES"
 264 The value of the flags correspond to extension values which are cached
 265 in the \fBX509\fR structure. If the flags returned do not provide sufficient
 266 information an application should examine extension values directly
 267 for example using \fBX509_get_ext_d2i()\fR.
 268 .PP
 269 If the key usage or extended key usage extension is absent then typically usage
 270 is unrestricted. For this reason \fBX509_get_key_usage()\fR and
 271 \&\fBX509_get_extended_key_usage()\fR return \fB\s-1UINT32_MAX\s0\fR when the corresponding
 272 extension is absent. Applications can additionally check the return value of
 273 \&\fBX509_get_extension_flags()\fR and take appropriate action is an extension is
 274 absent.
 275 .PP
 276 If \fBX509_get0_subject_key_id()\fR returns \fB\s-1NULL\s0\fR then the extension may be
 277 absent or malformed. Applications can determine the precise reason using
 278 \&\fBX509_get_ext_d2i()\fR.
 279 .SH "RETURN VALUES"
 280 .IX Header "RETURN VALUES"
 281 \&\fBX509_get_pathlen()\fR returns the path length value, or \-1 if the extension
 282 is not present.
 283 .PP
 284 \&\fBX509_get_extension_flags()\fR, \fBX509_get_key_usage()\fR and
 285 \&\fBX509_get_extended_key_usage()\fR return sets of flags corresponding to the
 286 certificate extension values.
 287 .PP
 288 \&\fBX509_get0_subject_key_id()\fR returns the subject key identifier as a
 289 pointer to an \fB\s-1ASN1_OCTET_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if the extension
 290 is absent or an error occurred during parsing.
 291 .PP
 292 \&\fBX509_get_proxy_pathlen()\fR returns the path length value if the given
 293 certificate is a proxy one and has a path length set, and \-1 otherwise.
 294 .SH "SEE ALSO"
 295 .IX Header "SEE ALSO"
 296 \&\fBX509_check_purpose\fR\|(3)
 297 .SH "HISTORY"
 298 .IX Header "HISTORY"
 299 \&\fBX509_get_pathlen()\fR, \fBX509_set_proxy_flag()\fR, \fBX509_set_proxy_pathlen()\fR and
 300 \&\fBX509_get_proxy_pathlen()\fR were added in OpenSSL 1.1.0.
 301 .SH "COPYRIGHT"
 302 .IX Header "COPYRIGHT"
 303 Copyright 2015\-2020 The OpenSSL Project Authors. All Rights Reserved.
 304 .PP
 305 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 306 this file except in compliance with the License.  You can obtain a copy
 307 in the file \s-1LICENSE\s0 in the source distribution or at
 308 <https://www.openssl.org/source/license.html>.