248 lines
6.8 KiB
Groff
248 lines
6.8 KiB
Groff
.\" $OpenBSD: X509_check_trust.3,v 1.8 2023/04/30 14:49:47 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: 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 .
|