Two new manual pages X509_TRUST_set(3) and X509_check_trust(3)

documenting ten functions related to X509_TRUST objects,
trust identifiers, and trust indices.

8 files changed, 516 insertions, 12 deletions

diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 300a37686af..c3dcaa06a3f 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.185 2021/07/23 14:27:32 schwarze Exp $
+# $OpenBSD: Makefile,v 1.186 2021/07/24 14:33:14 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -305,6 +305,7 @@ MAN=	\
 	X509_STORE_new.3 \
 	X509_STORE_set_verify_cb_func.3 \
 	X509_STORE_set1_param.3 \
+	X509_TRUST_set.3 \
 	X509_VERIFY_PARAM_set_flags.3 \
 	X509_add1_trust_object.3 \
 	X509_check_ca.3 \
@@ -312,6 +313,7 @@ MAN=	\
 	X509_check_issued.3 \
 	X509_check_private_key.3 \
 	X509_check_purpose.3 \
+	X509_check_trust.3 \
 	X509_cmp.3 \
 	X509_cmp_time.3 \
 	X509_digest.3 \
diff --git a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3 b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
index 89677a7cb3c..b097bbbeccd 100644
--- a/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
+++ b/lib/libcrypto/man/PEM_read_bio_PrivateKey.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.19 2020/07/23 17:34:53 schwarze Exp $
+.\" $OpenBSD: PEM_read_bio_PrivateKey.3,v 1.20 2021/07/24 14:33:14 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/PEM_read_bio_PrivateKey.pod 18bad535 Apr 9 15:13:55 2019 +0100
 .\" OpenSSL man3/PEM_read_CMS.pod 83cf7abf May 29 13:07:08 2018 +0100
@@ -51,7 +51,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 23 2020 $
+.Dd $Mdocdate: July 24 2021 $
 .Dt PEM_READ_BIO_PRIVATEKEY 3
 .Os
 .Sh NAME
@@ -924,6 +924,9 @@ The
 functions process a trusted X509 certificate using an
 .Vt X509
 structure.
+The
+.Xr X509_check_trust 3
+manual explains how the auxiliary trust information is used.
 .Pp
 The
 .Sy X509_REQ
diff --git a/lib/libcrypto/man/X509_CINF_new.3 b/lib/libcrypto/man/X509_CINF_new.3
index 9b87aaa77b3..f7de4d95249 100644
--- a/lib/libcrypto/man/X509_CINF_new.3
+++ b/lib/libcrypto/man/X509_CINF_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: X509_CINF_new.3,v 1.9 2021/07/12 15:56:54 schwarze Exp $
+.\"	$OpenBSD: X509_CINF_new.3,v 1.10 2021/07/24 14:33:14 schwarze Exp $
 .\"
 .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 12 2021 $
+.Dd $Mdocdate: July 24 2021 $
 .Dt X509_CINF_NEW 3
 .Os
 .Sh NAME
@@ -96,6 +96,7 @@ if an error occurs.
 .Xr d2i_X509_CINF 3 ,
 .Xr X509_add1_trust_object 3 ,
 .Xr X509_CERT_AUX_print 3 ,
+.Xr X509_check_trust 3 ,
 .Xr X509_keyid_set1 3 ,
 .Xr X509_new 3
 .Sh STANDARDS
diff --git a/lib/libcrypto/man/X509_TRUST_set.3 b/lib/libcrypto/man/X509_TRUST_set.3
new file mode 100644
index 00000000000..f363ead18bd
--- /dev/null
+++ b/lib/libcrypto/man/X509_TRUST_set.3
@@ -0,0 +1,286 @@
+.\" $OpenBSD: X509_TRUST_set.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_TRUST_SET 3
+.Os
+.Sh NAME
+.Nm X509_TRUST_set ,
+.Nm X509_TRUST_get_by_id ,
+.Nm X509_TRUST_add ,
+.Nm X509_TRUST_get_count ,
+.Nm X509_TRUST_cleanup ,
+.Nm X509_TRUST_get0 ,
+.Nm X509_TRUST_get_trust ,
+.Nm X509_TRUST_get0_name ,
+.Nm X509_TRUST_get_flags
+.Nd trust objects, indices, and identifiers
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo X509_TRUST_set
+.Fa "int *id_out"
+.Fa "int id_in"
+.Fc
+.Ft int
+.Fn X509_TRUST_get_by_id "int identifier"
+.Ft int
+.Fo X509_TRUST_add
+.Fa "int identifier"
+.Fa "int flags"
+.Fa "int (*check_trust)(X509_TRUST *, X509 *, int)"
+.Fa "const char *name"
+.Fa "int arg1"
+.Fa "void *arg2"
+.Fc
+.Ft int
+.Fn X509_TRUST_get_count void
+.Ft void
+.Fn X509_TRUST_cleanup void
+.Ft X509_TRUST *
+.Fn X509_TRUST_get0 "int index"
+.Ft int
+.Fn X509_TRUST_get_trust "const X509_TRUST *object"
+.Ft char *
+.Fn X509_TRUST_get0_name "const X509_TRUST *object"
+.Ft int
+.Fn X509_TRUST_get_flags "const X509_TRUST *object"
+.Sh DESCRIPTION
+The purposes that an X.509 certificate is trusted for
+can be identified in three equivalent ways:
+.Bl -enum
+.It
+By trust identifiers, which are positive integer constants.
+Standard trust identifiers lie in the range from
+.Dv X509_TRUST_MIN
+to
+.Dv X509_TRUST_MAX ,
+inclusive.
+User defined trust identifiers are larger than
+.Dv X509_TRUST_MAX .
+.It
+By trust indices, which are non-negative integer constants but
+differ from the trust identifiers expressing the same kind of trust.
+Standard trust indices are smaller than
+.Dv X509_TRUST_MAX .
+User defined trust indices are larger than or equal to
+.Dv X509_TRUST_MAX .
+.It
+By trust objects of the type
+.Vt X509_TRUST .
+Standard trust objects are available in static storage.
+User defined trust objects can be created with
+.Fn X509_TRUST_add .
+.El
+.Pp
+Application programmers cannot choose the way to identify kinds of trust
+that they like best; depending on the circumstances, all three ways
+are needed.
+Be warned that the naming of most functions is misleading.
+.Pp
+Most API functions documented outside the present manual page
+use trust identifiers rather than trust indices.
+.Pp
+ASN.1 object identifiers and NIDs provide a fourth and a fifth way
+to identify purposes that a certificate is trusted for.
+These are almost, but not exactly, equivalent
+to the three ways listed above; see the
+.Xr X509_check_trust 3
+manual for details.
+.Ss Using trust identifiers
+.Fn X509_TRUST_set
+validates the trust identifier
+.Fa id_in .
+If it is valid, it is copied to
+.Pf * Fa id_out .
+Otherwise,
+.Pf * Fa id_out
+remains unchanged.
+.Pp
+.Fn X509_TRUST_get_by_id
+converts the trust
+.Fa identifier
+to the corresponding trust
+.Fa index .
+To find the corresponding trust object, pass the result to
+.Fn X509_TRUST_get0 .
+.Pp
+.Fn X509_TRUST_add
+defines a purpose certificates can be trusted for with the given
+.Fa identifier
+or modifies its properties if it already exists.
+The trust
+.Fa identifier ,
+the
+.Fa flags ,
+the
+.Fa check_trust
+function, the
+.Fa name ,
+the number
+.Fa arg1 ,
+and the pointer
+.Fa arg2
+are copied into the
+.Vt X509_TRUST
+object.
+When modifying an existing trust object, previous
+values of fields are overwritten and a previous
+.Fa name
+string is freed if it was dynamically allocated.
+When creating a new trust object,
+it is added to the global array of user-defined trust objects.
+.Pp
+.Dv X509_TRUST_DYNAMIC
+and
+.Dv X509_TRUST_DYNAMIC_NAME
+are always ignored in the
+.Fa flags
+argument.
+.Dv X509_TRUST_DYNAMIC
+is automatically set if the object was created by the user.
+It is never set for standard objects,
+not even if they were modified by the user.
+.Dv X509_trust_DYNAMIC_NAME
+is automatically set if the object was created or modified by the user.
+It is only unset for unmodified standard objects.
+The library does not appear to define any other flags,
+so the flags argument is probably useless
+unless users define their own flags and use them in the
+.Fa check_trust
+function.
+.Pp
+The third and final argument of the
+.Fa check_trust
+function is the
+.Fa flags
+argument of
+.Fn X509_check_trust .
+.Pp
+The built-in trust checking functions documented in the
+.Xr X509_check_trust 3
+manual page use
+.Fa arg1
+as the corresponding ASN.1 object NID and ignore
+.Fa arg2
+and
+.Fa flags ,
+but a user-supplied
+.Fa check_trust
+function can use these fields in any arbitrary way.
+.Pp
+.Fn X509_TRUST_get_count
+returns the total number of trust objects currently existing,
+including both standard and user-defined objects.
+If no user-defined objects exist, the returned value is
+.Dv X509_TRUST_MAX .
+.Pp
+.Fn X509_TRUST_cleanup
+deletes all user-defined trust objects
+and invalidates their trust identifiers and trust indices.
+If any of the standard trust objects were modified by the user,
+those changes are
+.Em not
+reverted.
+.Ss Using trust indices
+.Fn X509_TRUST_get0
+converts the trust
+.Fa index
+to a pointer to the corresponding trust object.
+To find the corresponding trust identifier, pass the result to
+.Fn X509_TRUST_get_trust .
+.Ss Using trust objects
+.Fn X509_TRUST_get_trust
+converts a pointer to a trust
+.Fa object
+to the corresponding trust identifier.
+To find the corresponding trust index, pass the result to
+.Fn X509_TRUST_get_by_id .
+.Pp
+.Fn X509_TRUST_get0_name
+and
+.Fn X509_TRUST_get_flags
+retrieve the name and flags from the
+.Fa object ,
+respectively.
+.Sh RETURN VALUES
+.Fn X509_TRUST_set
+returns 1 if
+.Fa id_in
+is valid or 0 otherwise.
+.Pp
+.Fn X509_TRUST_get_by_id
+returns the corresponding trust index or -1 if the
+.Fa identifier
+is invalid.
+.Pp
+.Fn X509_TRUST_add
+returns 1 for success or 0 for failure.
+.Pp
+.Fn X509_TRUST_get_count
+returns the total number of trust objects currently existing.
+.Pp
+.Fn X509_TRUST_get0
+returns a standard or user-defined trust object or
+.Dv NULL
+if the
+.Fa index
+is invalid.
+.Pp
+.Fn X509_TRUST_get_trust
+always returns a valid trust identifier.
+.Pp
+.Fn X509_TRUST_get0_name
+returns a pointer to storage owned by the
+.Fa object .
+.Pp
+.Fn X509_TRUST_get_flags
+returns the flags associated with the
+.Fa object .
+.Sh ERRORS
+The following diagnostics can be retrieved with
+.Xr ERR_get_error 3 ,
+.Xr ERR_GET_REASON 3 ,
+and
+.Xr ERR_reason_error_string 3 :
+.Bl -tag -width Ds
+.It Dv X509_R_INVALID_TRUST Qq "invalid trust"
+.Fn X509_TRUST_set
+was called with an invalid
+.Fa id_in
+argument.
+.It Dv ERR_R_MALLOC_FAILURE Qq "malloc failure"
+.Fn X509_TRUST_add
+failed to allocate memory.
+.El
+.Pp
+The other functions provide no diagnostics.
+.Sh SEE ALSO
+.Xr X509_check_trust 3 ,
+.Xr X509_new 3 ,
+.Xr X509_PURPOSE_set 3 ,
+.Xr X509_VERIFY_PARAM_set_trust 3
+.Sh HISTORY
+.Fn X509_TRUST_set
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
+.Pp
+The other functions first appeared in OpenSSL 0.9.5
+and have been available since
+.Ox 2.7 .
+.Sh CAVEATS
+The difference between trust identifiers and trust indices
+provides an ideal breeding ground for off-by-one bugs.
diff --git a/lib/libcrypto/man/X509_add1_trust_object.3 b/lib/libcrypto/man/X509_add1_trust_object.3
index 3c1ae52e691..e1e38242085 100644
--- a/lib/libcrypto/man/X509_add1_trust_object.3
+++ b/lib/libcrypto/man/X509_add1_trust_object.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_add1_trust_object.3,v 1.2 2021/07/08 13:07:00 schwarze Exp $
+.\" $OpenBSD: X509_add1_trust_object.3,v 1.3 2021/07/24 14:33:14 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 8 2021 $
+.Dd $Mdocdate: July 24 2021 $
 .Dt X509_ADD1_TRUST_OBJECT 3
 .Os
 .Sh NAME
@@ -93,6 +93,7 @@ does not contain a sub-object that can hold non-standard auxiliary data.
 .Xr EXTENDED_KEY_USAGE_new 3 ,
 .Xr OBJ_nid2obj 3 ,
 .Xr X509_CERT_AUX_new 3 ,
+.Xr X509_check_trust 3 ,
 .Xr X509_new 3
 .Sh HISTORY
 These functions first appeared in OpenSSL 0.9.4 and have been available since
diff --git a/lib/libcrypto/man/X509_check_purpose.3 b/lib/libcrypto/man/X509_check_purpose.3
index b03eb5e4693..56f61095411 100644
--- a/lib/libcrypto/man/X509_check_purpose.3
+++ b/lib/libcrypto/man/X509_check_purpose.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_check_purpose.3,v 1.4 2021/07/23 16:22:59 schwarze Exp $
+.\" $OpenBSD: X509_check_purpose.3,v 1.5 2021/07/24 14:33:14 schwarze Exp $
 .\"
 .\" Copyright (c) 2019, 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" 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 23 2021 $
+.Dd $Mdocdate: July 24 2021 $
 .Dt X509_CHECK_PURPOSE 3
 .Os
 .Sh NAME
@@ -380,6 +380,7 @@ can be used as a CA for the
 .Sh SEE ALSO
 .Xr BASIC_CONSTRAINTS_new 3 ,
 .Xr EXTENDED_KEY_USAGE_new 3 ,
+.Xr X509_check_trust 3 ,
 .Xr X509_new 3 ,
 .Xr X509_PURPOSE_set 3 ,
 .Xr X509V3_get_d2i 3 ,
diff --git a/lib/libcrypto/man/X509_check_trust.3 b/lib/libcrypto/man/X509_check_trust.3
new file mode 100644
index 00000000000..4b625fdfd4d
--- /dev/null
+++ b/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 .
diff --git a/lib/libcrypto/man/X509_new.3 b/lib/libcrypto/man/X509_new.3
index ef99015ddb6..e06203f87c6 100644
--- a/lib/libcrypto/man/X509_new.3
+++ b/lib/libcrypto/man/X509_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_new.3,v 1.25 2021/07/23 14:27:32 schwarze Exp $
+.\" $OpenBSD: X509_new.3,v 1.26 2021/07/24 14:33:14 schwarze Exp $
 .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: July 23 2021 $
+.Dd $Mdocdate: July 24 2021 $
 .Dt X509_NEW 3
 .Os
 .Sh NAME
@@ -176,6 +176,7 @@ if an error occurs.
 .Xr X509_check_issued 3 ,
 .Xr X509_check_private_key 3 ,
 .Xr X509_check_purpose 3 ,
+.Xr X509_check_trust 3 ,
 .Xr X509_CINF_new 3 ,
 .Xr X509_cmp 3 ,
 .Xr X509_CRL_new 3 ,
@@ -199,7 +200,8 @@ if an error occurs.
 .Xr X509_SIG_new 3 ,
 .Xr X509_sign 3 ,
 .Xr X509_STORE_CTX_new 3 ,
-.Xr X509_STORE_new 3
+.Xr X509_STORE_new 3 ,
+.Xr X509_TRUST_set 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 Certificate Revocation List (CRL) Profile