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.
- 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_REJECTEDis returned. - 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_TRUSTEDis returned. - 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_UNTRUSTEDis returned. - 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_TRUSTEDis returned. - Otherwise,
X509_TRUST_UNTRUSTEDis 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_TRUSTEDis 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.