NAME

X509_check_purpose — check intended usage of a public key

SYNOPSIS

#include <openssl/x509v3.h> int
X509_check_purpose(X509 *certificate, int purpose, int ca);

DESCRIPTION

If the purpose argument is -1, X509_check_purpose() ignores the ca argument and checks that all the extensions of the certificate can be parsed and pass minimal sanity checks, ensuring that no extension occurs more than once. It also makes sure that all extensions are cached in the X509 object. If the purpose argument is not -1 and the ca flag is 0, X509_check_purpose() also checks whether the public key contained in the certificate is intended to be used for the given purpose, which can be one of the following integer constants. The check succeeds if none of the conditions given in the list below are violated. It always fails if parsing fails for any extension contained in the certificate.

X509_PURPOSE_SSL_CLIENT

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW client authentication” purpose (NID_client_auth).
• If the certificate contains a Key Usage extension, the digitalSignature bit is set.
• If the certificate contains a Netscape Cert Type extension, the “SSL client certificate” bit is set (NS_SSL_CLIENT).

X509_PURPOSE_SSL_SERVER

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW server authentication” purpose (NID_server_auth) or the private “Netscape Server Gated Crypto” (NID_ns_sgc) or “Microsoft Server Gated Crypto” (NID_ms_sgc) purpose.
• If the certificate contains a Key Usage extension, at least one of the digitalSignature and keyEncipherment bits is set.
• If the certificate contains a Netscape Cert Type extension, the “SSL server certificate” bit is set (NS_SSL_SERVER)

X509_PURPOSE_NS_SSL_SERVER

This does the same checks as X509_PURPOSE_SSL_SERVER and additionally requires that a Key Usage extension, if present, has the keyEncipherment bit set.

X509_PURPOSE_SMIME_SIGN

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID_email_protect).
• If the certificate contains a Key Usage extension, at least one of the digitalSignature and nonRepudiation bits is set.
• If the certificate contains a Netscape Cert Type extension, it has the “S/MIME certificate” bit set. If the “SSL client certificate” bit is set but the “S/MIME certificate” bit is not, no decision is made.

X509_PURPOSE_SMIME_ENCRYPT

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID_email_protect).
• If the certificate contains a Key Usage extension, the keyEncipherment bit is set.
• If the certificate contains a Netscape Cert Type extension, it has the “S/MIME certificate” bit set. If the “SSL client certificate” bit is set but the “S/MIME certificate” bit is not, no decision is made.

X509_PURPOSE_CRL_SIGN

• If the certificate contains a Key Usage extension, the cRLSign bit is set.

X509_PURPOSE_ANY

Nothing is required except that, if any extensions are present, parsing them needs to succeed.

X509_PURPOSE_OCSP_HELPER

Nothing is required except that, if any extensions are present, parsing them needs to succeed. The application program is expected to do the actual checking by other means.

X509_PURPOSE_TIMESTAMP_SIGN

• The certificate contains an Extended Key Usage extension containing the RFC 5280 “Time Stamping” purpose and no other purpose. This extension is marked as critical.
• If the certificate contains a Key Usage extension, at least one of the digitalSignature and nonRepudiation bits is set, and no other bits are set.

If the purpose argument is not -1 and the ca flag is non-zero, X509_check_purpose() instead checks, in addition to the minimal sanity checks, whether the certificate can be used as a certificate authority certificate in the context of the given purpose. To succeed, the check always requires that none of the following conditions are violated:

• If the certificate contains any extensions, parsing them succeeds.
• If the certificate contains a Key Usage extension, the keyCertSign bit is set.
• If the certificate contains a Basic Constraints extension, the cA field is set.
• If the certificate is a version 1 certificate, the subject name matches the issuer name and the certificate is self signed.

The check succeeds if none of the additional conditions given in the list below are violated.

X509_PURPOSE_SSL_CLIENT

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW client authentication” purpose (NID_client_auth).
• If the certificate is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “SSL CA certificate” bit set.

X509_PURPOSE_SSL_SERVER or X509_PURPOSE_NS_SSL_SERVER

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “TLS WWW server authentication” purpose (NID_server_auth) or the private “Netscape Server Gated Crypto” (NID_ns_sgc) or “Microsoft Server Gated Crypto” (NID_ms_sgc) purpose.
• If the certificate is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “SSL CA certificate” bit set.

X509_PURPOSE_SMIME_SIGN or X509_PURPOSE_SMIME_ENCRYPT

• If the certificate contains an Extended Key Usage extension, it contains the RFC 5280 “Email protection” purpose (NID_email_protect).
• If the certificate is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with the “S/MIME CA certificate” bit set.

X509_PURPOSE_CRL_SIGN, X509_PURPOSE_OCSP_HELPER, or X509_PURPOSE_TIMESTAMP_SIGN

• If the certificate is not a version 1 certificate and does not contain a Basic Constraints extension, it contains a Key Usage extension with the keyCertSign bit set or a Netscape Cert Type extension with at least one of the “SSL CA certificate”, “S/MIME CA certificate”, or “Object-signing CA certificate” bits set.

X509_PURPOSE_ANY

Nothing is required except that, if any extensions are present, parsing them needs to succeed. The check even succeeds if the three other common conditions cited above this list are violated.

If the function X509_PURPOSE_add(3) was called before X509_check_purpose(), it may have installed different, user-supplied checking functions for some of the standard purposes listed above, or it may have installed additional, user-supplied checking functions for user-defined purpose identifiers not listed above.

RETURN VALUES

If the parsing of certificate extensions fails, sanity checks fail or the purpose is invalid, X509_check_purpose() returns -1 to indicate the error. If the purpose argument is -1 and parsing and minimal sanity checks succeed, X509_check_purpose() returns 1 to indicate success. Otherwise, it returns the following values: If ca is 0:

0	Failure	The certificate cannot be used for the purpose.
1	Success	The certificate can be used for the purpose.
2	Unknown	No decision can be made.

If ca is non-zero:

0	Failure	The certificate cannot be used as a CA for the purpose.
1	Success	The certificate can be used as a CA for the purpose.
3	Success	The certificate is a version 1 CA.
4	Success	The Key Usage allows keyCertSign.
5	Success	A Netscape Cert Type allows usage as a CA.

SEE ALSO

BASIC_CONSTRAINTS_new(3), EXTENDED_KEY_USAGE_new(3), X509_check_trust(3), X509_new(3), X509_PURPOSE_set(3), X509V3_get_d2i(3), x509v3.cnf(5)

STANDARDS

RFC 5280: Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile

• section 4.2.1.3: Key Usage
• section 4.2.1.9: Basic Constraints
• section 4.2.1.12: Extended Key Usage

HISTORY

X509_check_purpose() first appeared in OpenSSL 0.9.5 and has been available since OpenBSD 2.7.