Document extension functions

Reviewed-by: Rich Salz <rsalz@openssl.org>

diff --git a/doc/crypto/X509_get_extension_flags.pod b/doc/crypto/X509_get_extension_flags.pod
new file mode 100644 (file)
index 0000000..2950bd7
--- /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