.\" $OpenBSD: X509_check_trust.3,v 1.8 2023/04/30 14:49:47 tb Exp $ .\" .\" Copyright (c) 2021 Ingo Schwarze .\" .\" Permission to use, copy, modify, and distribute this software for any .\" purpose with or without fee is hereby granted, provided that the above .\" copyright notice and this permission notice appear in all copies. .\" .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .Dd $Mdocdate: April 30 2023 $ .Dt X509_CHECK_TRUST 3 .Os .Sh NAME .Nm X509_check_trust , .Nm X509_TRUST_set_default .Nd check whether a certificate is trusted .Sh SYNOPSIS .In openssl/x509.h .Ft int .Fo X509_check_trust .Fa "X509 *certificate" .Fa "int trust" .Fa "int flags" .Fc .Ft int .Fo "(*X509_TRUST_set_default(int (*handler)(int, X509 *, int)))" .Fa "int trust" .Fa "X509 *certificate" .Fa "int flags" .Fc .Sh DESCRIPTION .Fn X509_check_trust checks whether the .Fa certificate is marked as trusted for the purpose corresponding to the requested .Fa trust identifier. .Pp 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. .Bl -enum .It If .Xr X509_add1_reject_object 3 was previously called on the .Fa certificate with the ASN.1 object identifier corresponding to the requested .Fa trust identifier, .Dv X509_TRUST_REJECTED is returned. .It If .Xr X509_add1_trust_object 3 was previously called on the .Fa certificate with the ASN.1 object identifier corresponding to the requested .Fa trust identifier, .Dv X509_TRUST_TRUSTED is returned. .It If .Xr X509_add1_reject_object 3 or .Xr X509_add1_trust_object 3 were previously called on the .Fa certificate , but neither of them with the ASN.1 object identifier corresponding to the requested .Fa trust identifier, .Dv X509_TRUST_UNTRUSTED is returned. .It This so-called .Dq compatibility step is skipped by some of the trust checking functions. If neither .Xr X509_add1_reject_object 3 nor .Xr X509_add1_trust_object 3 was previously called on the .Fa certificate and if the .Fa certificate is a self-signed, .Dv X509_TRUST_TRUSTED is returned. .It Otherwise, .Dv X509_TRUST_UNTRUSTED is returned. .El .Pp By default, the following .Fa trust identifiers are supported. The .Dq ASN.1 NID column indicates the corresponding ASN.1 object identifier; for the relationship between ASN.1 NIDs and OIDs, see the .Xr OBJ_nid2obj 3 manual page. The .Qq compat column indicates whether the compatibility step in the standard algorithm detailed above is used or skipped. .Pp .Bl -column X509_TRUST_OCSP_REQUEST NID_anyExtendedKeyUsage compat -compact .It Fa trust No identifier Ta Em ASN.1 NID Ta Em compat .It Dv X509_TRUST_SSL_CLIENT Ta Dv NID_client_auth Ta use .It Dv X509_TRUST_SSL_SERVER Ta Dv NID_server_auth Ta use .It Dv X509_TRUST_EMAIL Ta Dv NID_email_protect Ta use .It Dv X509_TRUST_OBJECT_SIGN Ta Dv NID_code_sign Ta use .It Dv X509_TRUST_OCSP_SIGN Ta Dv NID_OCSP_sign Ta skip .It Dv X509_TRUST_OCSP_REQUEST Ta Dv NID_ad_OCSP Ta skip .It Dv X509_TRUST_TSA Ta Dv NID_time_stamp Ta use .It Dv X509_TRUST_COMPAT Ta none Ta only .It 0 Ta Dv NID_anyExtendedKeyUsage Ta special .It \-1 Ta none Ta trusted .It invalid Ta Fa trust No argument Ta skip .El .Pp For the following .Fa trust identifiers, the standard algorithm is modified: .Bl -tag -width Ds .It Dv X509_TRUST_COMPAT .Xr X509_add1_reject_object 3 and .Xr X509_add1_trust_object 3 settings are completely ignored and all steps before the compatibility step are skipped. The .Fa certificate is trusted if and only if it is self-signed. .It 0 The third step in the standard algorithm is skipped, and the compatibility step is used even if .Xr X509_add1_reject_object 3 or .Xr X509_add1_trust_object 3 were called with ASN.1 object identifiers not corresponding to .Dv NID_anyExtendedKeyUsage . .It \-1 The .Fa certificate is not inspected and .Dv X509_TRUST_TRUSTED is always returned. .It invalid If the .Fa 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. .El .Pp The .Fa flags argument is ignored by all built-in trust checking functions, but user-specified trust checking functions might use it. .Pp If the function .Xr X509_TRUST_add 3 was called before .Fn X509_check_trust , it may have installed different, user-supplied checking functions for some of the standard .Fa trust identifiers listed above, or it may have installed additional, user-supplied checking functions for user-defined .Fa trust identifiers not listed above. .Pp If the function .Fn X509_TRUST_set_default was called, the .Fa handler function passed to it is used instead of the standard algorithm, but only in the case where the .Fa trust argument of .Fn X509_check_trust is invalid. The compatibility step is not used in this case. .Pp If the return value of the first call to .Fn X509_TRUST_set_default is saved and passed back to .Fn X509_TRUST_set_default later on, the standard behaviour of using the standard algorithm for invalid .Fa trust arguments is restored. .Sh RETURN VALUES .Fn X509_check_trust returns the following values: .Bl -tag -width Ds .It Dv X509_TRUST_TRUSTED The .Fa certificate is explicitly or implicitly trusted for the requested purpose. .It Dv X509_TRUST_REJECTED The .Fa certificate is explicitly rejected for the requested purpose. .It Dv X509_TRUST_UNTRUSTED The .Fa certificate is neither trusted nor explicitly rejected, which implies that it is not trusted. .El .Pp .Fn X509_TRUST_set_default returns a pointer to the handler function for invalid .Fa trust that was installed before the call, which may either be a pointer to a function installed by a previous call to .Fn X509_TRUST_set_default or a pointer to the built-in function implementing the standard algorithm if .Fn X509_TRUST_set_default was never called before. .Sh SEE ALSO .Xr PEM_read_X509_AUX 3 , .Xr X509_add1_trust_object 3 , .Xr X509_CERT_AUX_new 3 , .Xr X509_check_purpose 3 , .Xr X509_new 3 , .Xr X509_TRUST_set 3 , .Xr X509_VERIFY_PARAM_set_trust 3 .Sh HISTORY .Fn X509_check_trust and .Fn X509_TRUST_set_default first appeared in OpenSSL 0.9.5 and has been available since .Ox 2.7 .