diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2015-09-01 18:56:58 +0100 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2015-09-01 20:37:45 +0100 |
commit | 361136f4b39de26edcc275f8fe1471bcb90feb64 (patch) | |
tree | 7fd1e0e0ee17df4bda714f0af724b7c745abfd57 | |
parent | 063f1f0c693a10aab6a7227df15d4120ed824856 (diff) |
Document extension functions
Reviewed-by: Rich Salz <rsalz@openssl.org>
-rw-r--r-- | doc/crypto/X509_get_extension_flags.pod | 115 |
1 files changed, 115 insertions, 0 deletions
diff --git a/doc/crypto/X509_get_extension_flags.pod b/doc/crypto/X509_get_extension_flags.pod new file mode 100644 index 0000000000..2950bd784c --- /dev/null +++ b/doc/crypto/X509_get_extension_flags.pod @@ -0,0 +1,115 @@ +=pod + +=head1 NAME + +X509_get_extension_flags, X509_get_key_usage, X509_get_extended_key_usage - +retrieve certificate extension flags. + +=head1 SYNOPSIS + + #include <openssl/x509v3.h> + + uint32_t X509_get_extension_flags(X509 *x); + uint32_t X509_get_key_usage(X509 *x); + uint32_t X509_get_extended_key_usage(X509 *x); + +=head1 DESCRIPTION + +These functions retrieve flags related to commonly used certificate extensions. + +X509_get_extension_flags() retrieves general information about a certificate, +it will return one or more of the following flags ored together. + +=over 4 + +=item B<EXFLAG_V1> + +The certificate is an obsolete version 1 certificate. + +=item B<EXFLAG_BCONS> + +The certificate contains a basic constraints extension. + +=item B<EXFLAG_CA> + +The certificate contains basic constraints and asserts the CA flag. + +=item B<EXFLAG_PROXY> + +The certificate is a valid proxy certificate. + +=item B<EXFLAG_SI> + +The certificate is self issued (that is subject and issuer names match). + +=item B<EXFLAG_SS> + +The subject and issuer names match and extension values imply it is self +signed. + +=item B<EXFLAG_FRESHEST> + +The freshest CRL extension is present in the certificate. + +=item B<EXFLAG_CRITICAL> + +The certificate contains an unhandled critical extension. + +=item B<EXFLAG_INVALID> + +Some certificate extension values are invalid or inconsistent. The +certificate should be rejected. + +=item B<EXFLAG_KUSAGE> + +The certificate contains a key usage extension. The value can be retrieved +using X509_get_key_usage(). + +=item B<EXFLAG_XKUSAGE> + +The certificate contains an extended key usage extension. The value can be +retrieved using X509_get_extended_key_usage(). + +=back + +X509_get_key_usage() returns the value of the key usage extension. If key +usage is present will return zero or more of the flags: +B<KU_DIGITAL_SIGNATURE>, B<KU_NON_REPUDIATION>, B<KU_KEY_ENCIPHERMENT>, +B<KU_DATA_ENCIPHERMENT>, B<KU_KEY_AGREEMENT>, B<KU_KEY_CERT_SIGN>, +B<KU_CRL_SIGN>, B<KU_ENCIPHER_ONLY> or B<KU_DECIPHER_ONLY> corresponding to +individual key usage bits. If key usage is absent then B<UINT32_MAX> is +returned. + +X509_get_extended_key_usage() returns the value of the extended key usage +extension. If extended key usage is present it will return zero or more of the +flags: B<XKU_SSL_SERVER>, B<XKU_SSL_CLIENT>, B<XKU_SMIME>, B<XKU_CODE_SIGN> +B<XKU_OCSP_SIGN>, B<XKU_TIMESTAMP>, B<XKU_DVCS> or B<XKU_ANYEKU>. These +correspond to the OIDs B<id-kp-serverAuth>, B<id-kp-clientAuth>, +B<id-kp-emailProtection>, B<id-kp-codeSigning>, B<id-kp-OCSPSigning>, +B<id-kp-timeStamping>, B<id-kp-dvcs> and B<anyExtendedKeyUsage> respectively. +Additionally B<XKU_SGC> is set if either Netscape or Microsoft SGC OIDs are +present. + +=head1 NOTES + +The value of the flags correspond to extension values which are cached +in the B<X509> structure. If the flags returned do not provide sufficient +information an application should examine extension values directly. + +If the key usage or extended key usage extension is absent then typically usage +is unrestricted. For this reason X509_get_key_usage() and +X509_get_extended_key_usage() return B<UINT32_MAX> when the corresponding +extension is absent. Applications can additionally check the return value of +X509_get_extension_flags() and take appropriate action is an extension is +absent. + +=head1 RETURN VALUE + +These functions all return sets of flags corresponding to the certificate +extension values. + +=head1 SEE ALSO + +L<X509_check_purpose(3)> + +=cut |