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 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. Linux 6.8.2-arch2-1 April 30, 2023 Linux 6.8.2-arch2-1