1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
|
.\" $OpenBSD: X509_check_trust.3,v 1.5 2021/11/26 13:48:21 jsg 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: November 26 2021 $
.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 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.
.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 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_policy_check 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 .
|
