summaryrefslogtreecommitdiff
path: root/lib/libcrypto/man/x509_verify.3
blob: b9fe13a54f34ab8180003d6c7f4d3d252f4021e0 (plain)
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
.\" $OpenBSD: x509_verify.3,v 1.2 2020/09/14 14:21:46 schwarze Exp $
.\"
.\" Copyright (c) 2020 Bob Beck <beck@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: September 14 2020 $
.Dt X509_VERIFY 3
.Os
.Sh NAME
.Nm x509_verify ,
.Nm x509_verify_ctx_new ,
.Nm x509_verify_ctx_free ,
.Nm x509_verify_ctx_set_max_depth ,
.Nm x509_verify_ctx_set_max_signatures ,
.Nm x509_verify_ctx_set_max_chains ,
.Nm x509_verify_ctx_set_purpose ,
.Nm x509_verify_ctx_set_intermediates ,
.Nm x509_verify_ctx_error_string ,
.Nm x509_verify_ctx_error_depth ,
.Nm x509_verify_ctx_chain
.Nd discover and verify X.509 certificate chains
.Sh SYNOPSIS
.In openssl/x509_verify.h
.Ft size_t
.Fo x509_verify
.Fa "X509_VERIFY_CTX *ctx"
.Fa "X509 *leaf"
.Fa "char *name"
.Fc
.Ft X509_VERIFY_CTX *
.Fo x509_verify_ctx_new
.Fa "STACK_OF(X509) *roots"
.Fc
.Ft void
.Fo x509_verify_ctx_free
.Fa "X509_VERIFY_CTX *ctx"
.Fc
.Ft int
.Fo x509_verify_ctx_set_max_depth
.Fa "X509_VERIFY_CTX *ctx"
.Fa "size_t max"
.Fc
.Ft int
.Fo x509_verify_ctx_set_max_signatures
.Fa "X509_VERIFY_CTX *ctx"
.Fa "size_t max"
.Fc
.Ft int
.Fo x509_verify_ctx_set_max_chains
.Fa "X509_VERIFY_CTX *ctx"
.Fa "size_t max"
.Fc
.Ft int
.Fo x509_verify_ctx_set_purpose
.Fa "X509_VERIFY_CTX *ctx"
.Fa "int purpose_id"
.Fc
.Ft int
.Fo x509_verify_ctx_set_intermediates
.Fa "X509_VERIFY_CTX *ctx"
.Fa "STACK_OF(X509) *intermediates"
.Fc
.Ft const char *
.Fo x509_verify_ctx_error_string
.Fa "X509_VERIFY_CTX *ctx"
.Fc
.Ft size_t
.Fo x509_verify_ctx_error_depth
.Fa "X509_VERIFY_CTX *ctx"
.Fc
.Ft STACK_OF(X509) *
.Fo x509_verify_ctx_chain
.Fa "X509_VERIFY_CTX *ctx"
.Fa "size_t index"
.Fc
.Sh DESCRIPTION
The
.Fn x509_verify
function attempts to discover and validate all certificate chains
for the
.Fa name
from the
.Fa leaf
certificate based on the parameters in
.Fa ctx .
Multiple chains may be built and validated.
Revocation checking is not done by this function, and should be
performed by the caller on any returned chains if so desired.
.Pp
.Fn x509_verify_ctx_new
allocates a new context using the trusted
.Fa roots .
In case of success, it increments the reference count of
.Fa roots .
.Pp
.Fn x509_verify_ctx_free
frees
.Fa ctx
and decrements the reference count of the
.Fa roots
and
.Fa intermediates
associated with it.
If
.Fa ctx
is
.Dv NULL ,
no action occurs.
.Pp
.Fn x509_verify_ctx_set_max_depth
sets the maximum depth of certificate chains that will be constructed to
.Fa max ,
which can be in the range from 1 to the default of 32.
.Pp
.Fn x509_verify_ctx_set_max_signatures
sets the maximum number of public key signature operations that will be
used when verifying certificate chains to
.Fa max ,
which can be in the range from 1 to 100000.
The default is 256.
.Pp
.Fn x509_verify_ctx_set_max_chains
sets the maximum number of chains which may be returned to
.Fa max ,
which can be in the range from 1 to the default of 8.
.Pp
.Fn x509_verify_ctx_set_purpose
sets the certificate purpose for validation to
.Fa purpose_id .
The
.Dv X509_PURPOSE_*
constants listed in
.Xr X509_check_purpose 3
can be used.
.Pp
.Fn x509_verify_ctx_set_intermediates
provides some intermediate certificates, typically received from
the peer, to be used for building chains.
In case of success, this function increases the reference count of
.Fa intermediates .
.Pp
.Fn x509_verify_ctx_error_string
extracts a description of the last error encountered by a previous
call to
.Fn x509_verify
from
.Fa ctx .
.Pp
.Fn x509_verify_ctx_error_depth
extracts the depth of the last error encountered by a previous
call to
.Fn x509_verify
from
.Fa ctx .
.Pp
.Fn x509_verify_ctx_chain
extracts the validated chain with the given
.Fa index
from
.Fa ctx
after a previous call to
.Fn x509_verify .
The
.Fa index
starts at 0, and it is an error to pass a number
greater than or equal to the return value of
.Fn x509_verify .
The returned chain is neither copied,
nor is its reference count increased.
.Sh RETURN VALUES
.Fn x509_verify
returns the number of chains successfully built and validated
or 0 on failure.
.Pp
.Fn x509_verify_ctx_new
returns a newly allocated context or
.Dv NULL
on failure.
.Pp
.Fn x509_verify_ctx_set_max_depth ,
.Fn x509_verify_ctx_set_max_signatures ,
.Fn x509_verify_ctx_set_max_chains ,
.Fn x509_verify_ctx_set_purpose ,
and
.Fn x509_verify_ctx_set_intermediates
return 1 on success or 0 on failure.
.Pp
.Fn x509_verify_ctx_error_string
returns a pointer to a human readable error string.
If no error occurred,
.Qq ok
is returned.
.Pp
.Fn x509_verify_ctx_chain
returns an internal pointer to a validated chain or
.Dv NULL
if
.Fa index
is greater than or equal to the number of chains
that were successfully built and validated.
The returned pointer becomes invalid when
.Fa ctx
is destroyed.
.Sh SEE ALSO
.Xr X509_verify_cert 3
.Sh HISTORY
These functions first appeared in
.Ox 6.8 .
.Sh AUTHORS
.An Bob Beck Aq Mt beck@openbsd.org