X509_CHECK_TRUST(3)

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 skippped. 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 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_policy_check(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.