NAME

X509_check_trust, X509_TRUST_set_default — check whether a certificate is trusted

SYNOPSIS

#include <openssl/x509.h> int
X509_check_trust(X509 *certificate, int trust, int flags); int
(*X509_TRUST_set_default(int (*handler)(int, X509 *, int)))(int trust, X509 *certificate, int flags);

DESCRIPTION

X509_check_trust() checks whether the certificate is marked as trusted for the purpose corresponding to the requested trust identifier. The standard algorithm used by all built-in trust checking functions performs the following tests in the following order. The first matching test terminates the algorithm and decides the return value.

1. If X509_add1_reject_object(3) was previously called on the certificate with the ASN.1 object identifier corresponding to the requested trust identifier, X509_TRUST_REJECTED is returned.
2. If X509_add1_trust_object(3) was previously called on the certificate with the ASN.1 object identifier corresponding to the requested trust identifier, X509_TRUST_TRUSTED is returned.
3. If X509_add1_reject_object(3) or X509_add1_trust_object(3) were previously called on the certificate, but neither of them with the ASN.1 object identifier corresponding to the requested trust identifier, X509_TRUST_UNTRUSTED is returned.
4. This so-called “compatibility” step is skipped by some of the trust checking functions. If neither X509_add1_reject_object(3) nor X509_add1_trust_object(3) was previously called on the certificate and if the certificate is a self-signed, X509_TRUST_TRUSTED is returned.
5. Otherwise, X509_TRUST_UNTRUSTED is returned.

By default, the following trust identifiers are supported. The “ASN.1 NID” column indicates the corresponding ASN.1 object identifier; for the relationship between ASN.1 NIDs and OIDs, see the OBJ_nid2obj(3) manual page. The “compat” column indicates whether the compatibility step in the standard algorithm detailed above is used or skipped.

trust identifier	ASN.1 NID	compat
X509_TRUST_SSL_CLIENT	NID_client_auth	use
X509_TRUST_SSL_SERVER	NID_server_auth	use
X509_TRUST_EMAIL	NID_email_protect	use
X509_TRUST_OBJECT_SIGN	NID_code_sign	use
X509_TRUST_OCSP_SIGN	NID_OCSP_sign	skip
X509_TRUST_OCSP_REQUEST	NID_ad_OCSP	skip
X509_TRUST_TSA	NID_time_stamp	use
X509_TRUST_COMPAT	none	only
0	NID_anyExtendedKeyUsage	special
-1	none	trusted
invalid	trust argument	skip

For the following trust identifiers, the standard algorithm is modified:

X509_TRUST_COMPAT

X509_add1_reject_object(3) and X509_add1_trust_object(3) settings are completely ignored and all steps before the compatibility step are skipped. The certificate is trusted if and only if it is self-signed.

0

The third step in the standard algorithm is skipped, and the compatibility step is used even if X509_add1_reject_object(3) or X509_add1_trust_object(3) were called with ASN.1 object identifiers not corresponding to NID_anyExtendedKeyUsage.

-1

The certificate is not inspected and X509_TRUST_TRUSTED is always returned.

invalid

If the trust argument is neither 0 nor -1 nor valid as a trust identifier, it is re-interpreted as an ASN.1 NID and used itself for the standard algorithm. The compatibility step is skipped in this case.

The flags argument is ignored by all built-in trust checking functions, but user-specified trust checking functions might use it. If the function X509_TRUST_add(3) was called before X509_check_trust(), it may have installed different, user-supplied checking functions for some of the standard trust identifiers listed above, or it may have installed additional, user-supplied checking functions for user-defined trust identifiers not listed above. If the function X509_TRUST_set_default() was called, the handler function passed to it is used instead of the standard algorithm, but only in the case where the trust argument of X509_check_trust() is invalid. The compatibility step is not used in this case. If the return value of the first call to X509_TRUST_set_default() is saved and passed back to X509_TRUST_set_default() later on, the standard behaviour of using the standard algorithm for invalid trust arguments is restored.

RETURN VALUES

X509_check_trust() returns the following values:

X509_TRUST_TRUSTED

The certificate is explicitly or implicitly trusted for the requested purpose.

X509_TRUST_REJECTED

The certificate is explicitly rejected for the requested purpose.

X509_TRUST_UNTRUSTED

The certificate is neither trusted nor explicitly rejected, which implies that it is not trusted.

X509_TRUST_set_default() returns a pointer to the handler function for invalid trust that was installed before the call, which may either be a pointer to a function installed by a previous call to X509_TRUST_set_default() or a pointer to the built-in function implementing the standard algorithm if X509_TRUST_set_default() was never called before.

SEE ALSO

PEM_read_X509_AUX(3), X509_add1_trust_object(3), X509_CERT_AUX_new(3), X509_check_purpose(3), X509_new(3), X509_TRUST_set(3), X509_VERIFY_PARAM_set_trust(3)

HISTORY

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