secure/lib/libcrypto/man/X509_get_extension_flags.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 "X509_GET_EXTENSION_FLAGS 3"
 132 .TH X509_GET_EXTENSION_FLAGS 3 "2018-11-20" "1.1.1a" "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_subject_key_id, X509_get0_authority_key_id, 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
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/x509v3.h>
 143 \&
 144 \& long X509_get_pathlen(X509 *x);
 145 \& uint32_t X509_get_extension_flags(X509 *x);
 146 \& uint32_t X509_get_key_usage(X509 *x);
 147 \& uint32_t X509_get_extended_key_usage(X509 *x);
 148 \& const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
 149 \& const ASN1_OCTET_STRING *X509_get0_authority_key_id(X509 *x);
 150 \& void X509_set_proxy_flag(X509 *x);
 151 \& void X509_set_proxy_pathlen(int l);
 152 \& long X509_get_proxy_pathlen(X509 *x);
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 These functions retrieve information related to commonly used certificate extensions.
 157 .PP
 158 \&\fIX509_get_pathlen()\fR retrieves the path length extension from a certificate.
 159 This extension is used to limit the length of a cert chain that may be
 160 issued from that \s-1CA.\s0
 161 .PP
 162 \&\fIX509_get_extension_flags()\fR retrieves general information about a certificate,
 163 it will return one or more of the following flags ored together.
 164 .IP "\fB\s-1EXFLAG_V1\s0\fR" 4
 165 .IX Item "EXFLAG_V1"
 166 The certificate is an obsolete version 1 certificate.
 167 .IP "\fB\s-1EXFLAG_BCONS\s0\fR" 4
 168 .IX Item "EXFLAG_BCONS"
 169 The certificate contains a basic constraints extension.
 170 .IP "\fB\s-1EXFLAG_CA\s0\fR" 4
 171 .IX Item "EXFLAG_CA"
 172 The certificate contains basic constraints and asserts the \s-1CA\s0 flag.
 173 .IP "\fB\s-1EXFLAG_PROXY\s0\fR" 4
 174 .IX Item "EXFLAG_PROXY"
 175 The certificate is a valid proxy certificate.
 176 .IP "\fB\s-1EXFLAG_SI\s0\fR" 4
 177 .IX Item "EXFLAG_SI"
 178 The certificate is self issued (that is subject and issuer names match).
 179 .IP "\fB\s-1EXFLAG_SS\s0\fR" 4
 180 .IX Item "EXFLAG_SS"
 181 The subject and issuer names match and extension values imply it is self
 182 signed.
 183 .IP "\fB\s-1EXFLAG_FRESHEST\s0\fR" 4
 184 .IX Item "EXFLAG_FRESHEST"
 185 The freshest \s-1CRL\s0 extension is present in the certificate.
 186 .IP "\fB\s-1EXFLAG_CRITICAL\s0\fR" 4
 187 .IX Item "EXFLAG_CRITICAL"
 188 The certificate contains an unhandled critical extension.
 189 .IP "\fB\s-1EXFLAG_INVALID\s0\fR" 4
 190 .IX Item "EXFLAG_INVALID"
 191 Some certificate extension values are invalid or inconsistent. The
 192 certificate should be rejected.
 193 .IP "\fB\s-1EXFLAG_KUSAGE\s0\fR" 4
 194 .IX Item "EXFLAG_KUSAGE"
 195 The certificate contains a key usage extension. The value can be retrieved
 196 using \fIX509_get_key_usage()\fR.
 197 .IP "\fB\s-1EXFLAG_XKUSAGE\s0\fR" 4
 198 .IX Item "EXFLAG_XKUSAGE"
 199 The certificate contains an extended key usage extension. The value can be
 200 retrieved using \fIX509_get_extended_key_usage()\fR.
 201 .PP
 202 \&\fIX509_get_key_usage()\fR returns the value of the key usage extension.  If key
 203 usage is present will return zero or more of the flags:
 204 \&\fB\s-1KU_DIGITAL_SIGNATURE\s0\fR, \fB\s-1KU_NON_REPUDIATION\s0\fR, \fB\s-1KU_KEY_ENCIPHERMENT\s0\fR,
 205 \&\fB\s-1KU_DATA_ENCIPHERMENT\s0\fR, \fB\s-1KU_KEY_AGREEMENT\s0\fR, \fB\s-1KU_KEY_CERT_SIGN\s0\fR,
 206 \&\fB\s-1KU_CRL_SIGN\s0\fR, \fB\s-1KU_ENCIPHER_ONLY\s0\fR or \fB\s-1KU_DECIPHER_ONLY\s0\fR corresponding to
 207 individual key usage bits. If key usage is absent then \fB\s-1UINT32_MAX\s0\fR is
 208 returned.
 209 .PP
 210 \&\fIX509_get_extended_key_usage()\fR returns the value of the extended key usage
 211 extension. If extended key usage is present it will return zero or more of the
 212 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
 213 \&\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
 214 correspond to the OIDs \fBid-kp-serverAuth\fR, \fBid-kp-clientAuth\fR,
 215 \&\fBid-kp-emailProtection\fR, \fBid-kp-codeSigning\fR, \fBid-kp-OCSPSigning\fR,
 216 \&\fBid-kp-timeStamping\fR, \fBid-kp-dvcs\fR and \fBanyExtendedKeyUsage\fR respectively.
 217 Additionally \fB\s-1XKU_SGC\s0\fR is set if either Netscape or Microsoft \s-1SGC\s0 OIDs are
 218 present.
 219 .PP
 220 \&\fIX509_get0_subject_key_id()\fR returns an internal pointer to the subject key
 221 identifier of \fBx\fR as an \fB\s-1ASN1_OCTET_STRING\s0\fR or \fB\s-1NULL\s0\fR if the extension
 222 is not present or cannot be parsed.
 223 .PP
 224 \&\fIX509_get0_authority_key_id()\fR returns an internal pointer to the authority key
 225 identifier of \fBx\fR as an \fB\s-1ASN1_OCTET_STRING\s0\fR or \fB\s-1NULL\s0\fR if the extension
 226 is not present or cannot be parsed.
 227 .PP
 228 \&\fIX509_set_proxy_flag()\fR marks the certificate with the \fB\s-1EXFLAG_PROXY\s0\fR flag.
 229 This is for the users who need to mark non\-RFC3820 proxy certificates as
 230 such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 231 .PP
 232 \&\fIX509_set_proxy_pathlen()\fR sets the proxy certificate path length for the given
 233 certificate \fBx\fR.  This is for the users who need to mark non\-RFC3820 proxy
 234 certificates as such, as OpenSSL only detects \s-1RFC3820\s0 compliant ones.
 235 .PP
 236 \&\fIX509_get_proxy_pathlen()\fR returns the proxy certificate path length for the
 237 given certificate \fBx\fR if it is a proxy certificate.
 238 .SH "NOTES"
 239 .IX Header "NOTES"
 240 The value of the flags correspond to extension values which are cached
 241 in the \fBX509\fR structure. If the flags returned do not provide sufficient
 242 information an application should examine extension values directly
 243 for example using \fIX509_get_ext_d2i()\fR.
 244 .PP
 245 If the key usage or extended key usage extension is absent then typically usage
 246 is unrestricted. For this reason \fIX509_get_key_usage()\fR and
 247 \&\fIX509_get_extended_key_usage()\fR return \fB\s-1UINT32_MAX\s0\fR when the corresponding
 248 extension is absent. Applications can additionally check the return value of
 249 \&\fIX509_get_extension_flags()\fR and take appropriate action is an extension is
 250 absent.
 251 .PP
 252 If \fIX509_get0_subject_key_id()\fR returns \fB\s-1NULL\s0\fR then the extension may be
 253 absent or malformed. Applications can determine the precise reason using
 254 \&\fIX509_get_ext_d2i()\fR.
 255 .SH "RETURN VALUES"
 256 .IX Header "RETURN VALUES"
 257 \&\fIX509_get_pathlen()\fR returns the path length value, or \-1 if the extension
 258 is not present.
 259 .PP
 260 \&\fIX509_get_extension_flags()\fR, \fIX509_get_key_usage()\fR and
 261 \&\fIX509_get_extended_key_usage()\fR return sets of flags corresponding to the
 262 certificate extension values.
 263 .PP
 264 \&\fIX509_get0_subject_key_id()\fR returns the subject key identifier as a
 265 pointer to an \fB\s-1ASN1_OCTET_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if the extension
 266 is absent or an error occurred during parsing.
 267 .PP
 268 \&\fIX509_get_proxy_pathlen()\fR returns the path length value if the given
 269 certificate is a proxy one and has a path length set, and \-1 otherwise.
 270 .SH "SEE ALSO"
 271 .IX Header "SEE ALSO"
 272 \&\fIX509_check_purpose\fR\|(3)
 273 .SH "HISTORY"
 274 .IX Header "HISTORY"
 275 \&\fIX509_get_pathlen()\fR, \fIX509_set_proxy_flag()\fR, \fIX509_set_proxy_pathlen()\fR and
 276 \&\fIX509_get_proxy_pathlen()\fR were added in OpenSSL 1.1.0.
 277 .SH "COPYRIGHT"
 278 .IX Header "COPYRIGHT"
 279 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
 280 .PP
 281 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 282 this file except in compliance with the License.  You can obtain a copy
 283 in the file \s-1LICENSE\s0 in the source distribution or at
 284 <https://www.openssl.org/source/license.html>.