OpenBSD manual page server

Manual Page Search Parameters
X509_CHECK_PURPOSE(3) Library Functions Manual X509_CHECK_PURPOSE(3)

X509_check_purpose — check intended usage of a public key

#include <openssl/x509v3.h>

int
X509_check_purpose(X509 *certificate, int purpose, int ca);

If the ca flag is 0, () 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.

  • 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).
  • 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)
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.
  • 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.
  • 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.
  • If the certificate contains a Key Usage extension, the cRLSign bit is set.
The check always succeeds.
The check always succeeds. The application program is expected to do the actual checking by other means.
  • 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 ca flag is non-zero, () instead 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:

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

  • 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.
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.
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_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.
The check always succeeds, even if the three common conditions cited above this list are violated.

If the purpose is -1, () always succeeds, no matter whether or not the ca flag is set.

X509_check_purpose() returns the following values:

-1 Error The purpose is invalid.
0 Failure The certificate cannot be used for the purpose.

If ca is 0, the following values can also be returned:

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

If ca is non-zero, the following values can also be returned:

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.

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

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

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

August 22, 2019 OpenBSD-6.6