secure/lib/libcrypto/man/X509_get_extension_flags.3

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