OpenBSD manual page server

Manual Page Search Parameters

X509_CHECK_TRUST(3) Library Functions Manual X509_CHECK_TRUST(3)

X509_check_trust, X509_TRUST_set_defaultcheck whether a certificate is trusted

#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);

() 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
use
use
use
use
skip
skip
use
none only
0 special
-1 none trusted
invalid trust argument skip

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

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 (), 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 () 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 () 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.

X509_check_trust() returns the following values:

The certificate is explicitly or implicitly trusted for the requested purpose.
The certificate is explicitly rejected for the requested purpose.
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.

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)

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

September 10, 2022 OpenBSD-current