doc/crypto/X509_get_extension_flags.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage -
   6 retrieve certificate extension flags.
   7
   8 =head1 SYNOPSIS
   9
  10    #include <openssl/x509v3.h>
  11
  12    uint32_t X509_get_extension_flags(X509 *x);
  13    uint32_t X509_get_key_usage(X509 *x);
  14    uint32_t X509_get_extended_key_usage(X509 *x);
  15    const ASN1_OCTET_STRING *X509_get0_subject_key_id(X509 *x);
  16
  17 =head1 DESCRIPTION
  18
  19 These functions retrieve flags related to commonly used certificate extensions.
  20
  21 X509_get_extension_flags() retrieves general information about a certificate,
  22 it will return one or more of the following flags ored together.
  23
  24 =over 4
  25
  26 =item B<EXFLAG_V1>
  27
  28 The certificate is an obsolete version 1 certificate.
  29
  30 =item B<EXFLAG_BCONS>
  31
  32 The certificate contains a basic constraints extension.
  33
  34 =item B<EXFLAG_CA>
  35
  36 The certificate contains basic constraints and asserts the CA flag.
  37
  38 =item B<EXFLAG_PROXY>
  39
  40 The certificate is a valid proxy certificate.
  41
  42 =item B<EXFLAG_SI>
  43
  44 The certificate is self issued (that is subject and issuer names match).
  45
  46 =item B<EXFLAG_SS>
  47
  48 The subject and issuer names match and extension values imply it is self
  49 signed.
  50
  51 =item B<EXFLAG_FRESHEST>
  52
  53 The freshest CRL extension is present in the certificate.
  54
  55 =item B<EXFLAG_CRITICAL>
  56
  57 The certificate contains an unhandled critical extension.
  58
  59 =item B<EXFLAG_INVALID>
  60
  61 Some certificate extension values are invalid or inconsistent. The
  62 certificate should be rejected.
  63
  64 =item B<EXFLAG_KUSAGE>
  65
  66 The certificate contains a key usage extension. The value can be retrieved
  67 using X509_get_key_usage().
  68
  69 =item B<EXFLAG_XKUSAGE>
  70
  71 The certificate contains an extended key usage extension. The value can be
  72 retrieved using X509_get_extended_key_usage().
  73
  74 =back
  75
  76 X509_get_key_usage() returns the value of the key usage extension.  If key
  77 usage is present will return zero or more of the flags:
  78 B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>,
  79 B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>,
  80 B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to
  81 individual key usage bits. If key usage is absent then B<UINT32_MAX> is
  82 returned.
  83
  84 X509_get_extended_key_usage() returns the value of the extended key usage
  85 extension. If extended key usage is present it will return zero or more of the
  86 flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN>
  87 B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These
  88 correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>,
  89 B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>,
  90 B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively.
  91 Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are
  92 present.
  93
  94 X509_get_extended_key_usage() return an internal pointer to the subject key
  95 identifier of B<x> as an B<ASN1_OCTET_STRING> or B<NULL> if the extension
  96 is not present or cannot be parsed.
  97
  98 =head1 NOTES
  99
 100 The value of the flags correspond to extension values which are cached
 101 in the B<X509> structure. If the flags returned do not provide sufficient
 102 information an application should examine extension values directly
 103 for example using X509_get_ext_d2i().
 104
 105 If the key usage or extended key usage extension is absent then typically usage
 106 is unrestricted. For this reason X509_get_key_usage() and
 107 X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding
 108 extension is absent. Applications can additionally check the return value of
 109 X509_get_extension_flags() and take appropriate action is an extension is
 110 absent.
 111
 112 If X509_get0_subject_key_id() returns B<NULL> then the extension may be
 113 absent or malformed. Applications can determine the precise reason using
 114 X509_get_ext_d2i().
 115
 116 =head1 RETURN VALUE
 117
 118 X509_get_extension_flags(), X509_get_key_usage() and
 119 X509_get_extended_key_usage() return sets of flags corresponding to the
 120 certificate extension values.
 121
 122 X509_get0_subject_key_id() returns the subject key identifier as a
 123 pointer to an B<ASN1_OCTET_STRING> structure or B<NULL> if the extension
 124 is absent or an error occurred during parsing.
 125
 126 =head1 SEE ALSO
 127
 128 L<X509_check_purpose(3)>
 129
 130 =cut