+++ /dev/null
-.\" $OpenBSD: X509_check_trust.3,v 1.10 2024/08/17 09:19:04 tb Exp $
-.\"
-.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
-.\"
-.\" 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: August 17 2024 $
-.Dt X509_CHECK_TRUST 3
-.Os
-.Sh NAME
-.Nm X509_check_trust
-.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
-.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.
-.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
-.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_VERIFY_PARAM_set_trust 3
-.Sh HISTORY
-.Fn X509_check_trust
-first appeared in OpenSSL 0.9.5 and has been available since
-.Ox 2.7 .
projects / openbsd / commitdiff