X509_CHECK_TRUST(3) Library Functions Manual 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 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. GNU April 30, 2023 X509_CHECK_TRUST(3)