1 files changed, 208 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/X509_check_trust.3 b/src/lib/libcrypto/man/X509_check_trust.3
new file mode 100644
index 0000000000..4b625fdfd4
--- /dev/null
+++ b/src/lib/libcrypto/man/X509_check_trust.3
@@ -0,0 +1,208 @@
+.\" $OpenBSD: X509_check_trust.3,v 1.1 2021/07/24 14:33:14 schwarze 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: July 24 2021 $
+.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 correspondig 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 skippped.
+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 explicitely rejected for the requested purpose.
+.It Dv X509_TRUST_UNTRUSTED
+The
+.Fa certificate
+is neither trusted nor explicitely 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_TRUST_set 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 .