NAME

SYNOPSIS

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

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.

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_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

HISTORY