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
|
.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote. \*(C+ will
.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds PI pi
. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
. ds L" ""
. ds R" ""
. ds C` ""
. ds C' ""
'br\}
.el\{\
. ds -- \|\(em\|
. ds PI \(*p
. ds L" ``
. ds R" ''
. ds C`
. ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
. if \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. if !\nF==2 \{\
. nr % 0
. nr F 2
. \}
. \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
. ds #H 0
. ds #V .8m
. ds #F .3m
. ds #[ \f1
. ds #] \fP
.\}
.if t \{\
. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
. ds #V .6m
. ds #F 0
. ds #[ \&
. ds #] \&
.\}
. \" simple accents for nroff and troff
.if n \{\
. ds ' \&
. ds ` \&
. ds ^ \&
. ds , \&
. ds ~ ~
. ds /
.\}
.if t \{\
. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
. \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
. \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
. \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
. ds : e
. ds 8 ss
. ds o a
. ds d- d\h'-1'\(ga
. ds D- D\h'-1'\(hy
. ds th \o'bp'
. ds Th \o'LP'
. ds ae ae
. ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "X509_VERIFY_CERT 3SSL"
.TH X509_VERIFY_CERT 3SSL "2023-10-23" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
X509_build_chain,
X509_verify_cert,
X509_STORE_CTX_verify \- build and verify X509 certificate chain
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/x509_vfy.h>
\&
\& STACK_OF(X509) *X509_build_chain(X509 *target, STACK_OF(X509) *certs,
\& X509_STORE *store, int with_self_signed,
\& OSSL_LIB_CTX *libctx, const char *propq);
\& int X509_verify_cert(X509_STORE_CTX *ctx);
\& int X509_STORE_CTX_verify(X509_STORE_CTX *ctx);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBX509_build_chain()\fR builds a certificate chain starting from \fItarget\fR
using the optional list of intermediate \s-1CA\s0 certificates \fIcerts\fR.
If \fIstore\fR is \s-1NULL\s0 it builds the chain as far down as possible, ignoring errors.
Else the chain must reach a trust anchor contained in \fIstore\fR.
It internally uses a \fBX509_STORE_CTX\fR structure associated with the library
context \fIlibctx\fR and property query string \fIpropq\fR, both of which may be \s-1NULL.\s0
In case there is more than one possibility for the chain, only one is taken.
.PP
On success it returns a pointer to a new stack of (up_ref'ed) certificates
starting with \fItarget\fR and followed by all available intermediate certificates.
A self-signed trust anchor is included only if \fItarget\fR is the trust anchor
of \fIwith_self_signed\fR is 1.
If a non-NULL stack is returned the caller is responsible for freeing it.
.PP
The \fBX509_verify_cert()\fR function attempts to discover and validate a
certificate chain based on parameters in \fIctx\fR.
The verification context, of type \fBX509_STORE_CTX\fR, can be constructed
using \fBX509_STORE_CTX_new\fR\|(3) and \fBX509_STORE_CTX_init\fR\|(3).
It usually includes a target certificate to be verified,
a set of certificates serving as trust anchors,
a list of non-trusted certificates that may be helpful for chain construction,
flags such as X509_V_FLAG_X509_STRICT, and various other optional components
such as a callback function that allows customizing the verification outcome.
A complete description of the certificate verification process is contained in
the \fBopenssl\-verification\-options\fR\|(1) manual page.
.PP
Applications rarely call this function directly but it is used by
OpenSSL internally for certificate validation, in both the S/MIME and
\&\s-1SSL/TLS\s0 code.
.PP
A negative return value from \fBX509_verify_cert()\fR can occur if it is invoked
incorrectly, such as with no certificate set in \fIctx\fR, or when it is called
twice in succession without reinitialising \fIctx\fR for the second call.
A negative return value can also happen due to internal resource problems
or because an internal inconsistency has been detected.
Applications must interpret any return value <= 0 as an error.
.PP
The \fBX509_STORE_CTX_verify()\fR behaves like \fBX509_verify_cert()\fR except that its
target certificate is the first element of the list of untrusted certificates
in \fIctx\fR unless a target certificate is set explicitly.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBX509_build_chain()\fR returns \s-1NULL\s0 on error, else a stack of certificates.
.PP
Both \fBX509_verify_cert()\fR and \fBX509_STORE_CTX_verify()\fR
return 1 if a complete chain can be built and validated,
otherwise they return 0, and in exceptional circumstances (such as malloc
failure and internal errors) they can also return a negative code.
.PP
If a complete chain can be built and validated both functions return 1.
If the certificate must be rejected on the basis of the data available
or any required certificate status data is not available they return 0.
If no definite answer possible they usually return a negative code.
.PP
On error or failure additional error information can be obtained by
examining \fIctx\fR using, for example, \fBX509_STORE_CTX_get_error\fR\|(3). Even if
verification indicated success, the stored error code may be different from
X509_V_OK, likely because a verification callback function has waived the error.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBX509_STORE_CTX_new\fR\|(3), \fBX509_STORE_CTX_init\fR\|(3),
\&\fBX509_STORE_CTX_get_error\fR\|(3)
.SH "HISTORY"
.IX Header "HISTORY"
\&\fBX509_build_chain()\fR and \fBX509_STORE_CTX_verify()\fR were added in OpenSSL 3.0.
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2009\-2022 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
|
