1=pod
2
3=head1 NAME
4
5SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
6
7=head1 SYNOPSIS
8
9 #include <openssl/ssl.h>
10
11 void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
12 int (*verify_callback)(int, X509_STORE_CTX *));
13 void SSL_set_verify(SSL *s, int mode,
14 int (*verify_callback)(int, X509_STORE_CTX *));
15 void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth);
16 void SSL_set_verify_depth(SSL *s, int depth);
17
18 int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
19
20=head1 DESCRIPTION
21
22SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
23specifies the B<verify_callback> function to be used. If no callback function
24shall be specified, the NULL pointer can be used for B<verify_callback>.
25
26SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
27specifies the B<verify_callback> function to be used. If no callback function
28shall be specified, the NULL pointer can be used for B<verify_callback>. In
29this case last B<verify_callback> set specifically for this B<ssl> remains. If
30no special B<callback> was set before, the default callback for the underlying
31B<ctx> is used, that was valid at the the time B<ssl> was created with
32L<SSL_new(3)|SSL_new(3)>.
33
34SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
35verification that shall be allowed for B<ctx>. (See the BUGS section.)
36
37SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
38verification that shall be allowed for B<ssl>. (See the BUGS section.)
39
40=head1 NOTES
41
42The verification of certificates can be controlled by a set of logically
43or'ed B<mode> flags:
44
45=over 4
46
47=item SSL_VERIFY_NONE
48
49B<Server mode:> the server will not send a client certificate request to the
50client, so the client will not send a certificate.
51
52B<Client mode:> if not using an anonymous cipher (by default disabled), the
53server will send a certificate which will be checked. The result of the
54certificate verification process can be checked after the TLS/SSL handshake
55using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function.
56The handshake will be continued regardless of the verification result.
57
58=item SSL_VERIFY_PEER
59
60B<Server mode:> the server sends a client certificate request to the client.
61The certificate returned (if any) is checked. If the verification process
| 1=pod
2
3=head1 NAME
4
5SSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters
6
7=head1 SYNOPSIS
8
9 #include <openssl/ssl.h>
10
11 void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
12 int (*verify_callback)(int, X509_STORE_CTX *));
13 void SSL_set_verify(SSL *s, int mode,
14 int (*verify_callback)(int, X509_STORE_CTX *));
15 void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth);
16 void SSL_set_verify_depth(SSL *s, int depth);
17
18 int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);
19
20=head1 DESCRIPTION
21
22SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
23specifies the B<verify_callback> function to be used. If no callback function
24shall be specified, the NULL pointer can be used for B<verify_callback>.
25
26SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
27specifies the B<verify_callback> function to be used. If no callback function
28shall be specified, the NULL pointer can be used for B<verify_callback>. In
29this case last B<verify_callback> set specifically for this B<ssl> remains. If
30no special B<callback> was set before, the default callback for the underlying
31B<ctx> is used, that was valid at the the time B<ssl> was created with
32L<SSL_new(3)|SSL_new(3)>.
33
34SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
35verification that shall be allowed for B<ctx>. (See the BUGS section.)
36
37SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
38verification that shall be allowed for B<ssl>. (See the BUGS section.)
39
40=head1 NOTES
41
42The verification of certificates can be controlled by a set of logically
43or'ed B<mode> flags:
44
45=over 4
46
47=item SSL_VERIFY_NONE
48
49B<Server mode:> the server will not send a client certificate request to the
50client, so the client will not send a certificate.
51
52B<Client mode:> if not using an anonymous cipher (by default disabled), the
53server will send a certificate which will be checked. The result of the
54certificate verification process can be checked after the TLS/SSL handshake
55using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function.
56The handshake will be continued regardless of the verification result.
57
58=item SSL_VERIFY_PEER
59
60B<Server mode:> the server sends a client certificate request to the client.
61The certificate returned (if any) is checked. If the verification process
|
95SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
96to which depth certificates in a chain are used during the verification
97procedure. If the certificate chain is longer than allowed, the certificates
98above the limit are ignored. Error messages are generated as if these
99certificates would not be present, most likely a
100X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
101The depth count is "level 0:peer certificate", "level 1: CA certificate",
102"level 2: higher level CA certificate", and so on. Setting the maximum
103depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
104allowing for the peer certificate and additional 9 CA certificates.
105
106The B<verify_callback> function is used to control the behaviour when the
107SSL_VERIFY_PEER flag is set. It must be supplied by the application and
108receives two arguments: B<preverify_ok> indicates, whether the verification of
109the certificate in question was passed (preverify_ok=1) or not
110(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
111for the certificate chain verification.
112
113The certificate chain is checked starting with the deepest nesting level
114(the root CA certificate) and worked upward to the peer's certificate.
115At each level signatures and issuer attributes are checked. Whenever
116a verification error is found, the error number is stored in B<x509_ctx>
117and B<verify_callback> is called with B<preverify_ok>=0. By applying
118X509_CTX_store_* functions B<verify_callback> can locate the certificate
119in question and perform additional steps (see EXAMPLES). If no error is
120found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
121before advancing to the next level.
122
123The return value of B<verify_callback> controls the strategy of the further
124verification process. If B<verify_callback> returns 0, the verification
125process is immediately stopped with "verification failed" state. If
126SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
127the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
128the verification process is continued. If B<verify_callback> always returns
1291, the TLS/SSL handshake will never be terminated because of this application
130experiencing a verification failure. The calling process can however
131retrieve the error code of the last verification error using
132L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its
133own error storage managed by B<verify_callback>.
134
135If no B<verify_callback> is specified, the default callback will be used.
136Its return value is identical to B<preverify_ok>, so that any verification
137failure will lead to a termination of the TLS/SSL handshake with an
138alert message, if SSL_VERIFY_PEER is set.
139
140=head1 BUGS
141
142In client mode, it is not checked whether the SSL_VERIFY_PEER flag
143is set, but whether SSL_VERIFY_NONE is not set. This can lead to
144unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not
145used as required (exactly one must be set at any time).
146
147The certificate verification depth set with SSL[_CTX]_verify_depth()
148stops the verification at a certain depth. The error message produced
149will be that of an incomplete certificate chain and not
150X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
151
152=head1 RETURN VALUES
153
154The SSL*_set_verify*() functions do not provide diagnostic information.
155
156=head1 EXAMPLES
157
158The following code sequence realizes an example B<verify_callback> function
159that will always continue the TLS/SSL handshake regardless of verification
160failure, if wished. The callback realizes a verification depth limit with
161more informational output.
162
163All verification errors are printed, informations about the certificate chain
164are printed on request.
165The example is realized for a server that does allow but not require client
166certificates.
167
168The example makes use of the ex_data technique to store application data
169into/retrieve application data from the SSL structure
170(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
171L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
172
173 ...
174 typedef struct {
175 int verbose_mode;
176 int verify_depth;
177 int always_continue;
178 } mydata_t;
179 int mydata_index;
180 ...
181 static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
182 {
183 char buf[256];
184 X509 *err_cert;
185 int err, depth;
186 SSL *ssl;
187 mydata_t *mydata;
188
189 err_cert = X509_STORE_CTX_get_current_cert(ctx);
190 err = X509_STORE_CTX_get_error(ctx);
191 depth = X509_STORE_CTX_get_error_depth(ctx);
192
193 /*
194 * Retrieve the pointer to the SSL of the connection currently treated
195 * and the application specific data stored into the SSL object.
196 */
197 ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
198 mydata = SSL_get_ex_data(ssl, mydata_index);
199
200 X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
201
202 /*
203 * Catch a too long certificate chain. The depth limit set using
204 * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
205 * that whenever the "depth>verify_depth" condition is met, we
206 * have violated the limit and want to log this error condition.
207 * We must do it here, because the CHAIN_TOO_LONG error would not
208 * be found explicitly; only errors introduced by cutting off the
209 * additional certificates would be logged.
210 */
211 if (depth > mydata->verify_depth) {
212 preverify_ok = 0;
213 err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
214 X509_STORE_CTX_set_error(ctx, err);
215 }
216 if (!preverify_ok) {
217 printf("verify error:num=%d:%s:depth=%d:%s\n", err,
218 X509_verify_cert_error_string(err), depth, buf);
219 }
220 else if (mydata->verbose_mode)
221 {
222 printf("depth=%d:%s\n", depth, buf);
223 }
224
225 /*
226 * At this point, err contains the last verification error. We can use
227 * it for something special
228 */
229 if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)
230 {
231 X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256);
232 printf("issuer= %s\n", buf);
233 }
234
235 if (mydata->always_continue)
236 return 1;
237 else
238 return preverify_ok;
239 }
240 ...
241
242 mydata_t mydata;
243
244 ...
245 mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
246
247 ...
248 SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
249 verify_callback);
250
251 /*
252 * Let the verify_callback catch the verify_depth error so that we get
253 * an appropriate error in the logfile.
254 */
255 SSL_CTX_set_verify_depth(verify_depth + 1);
256
257 /*
258 * Set up the SSL specific data into "mydata" and store it into th SSL
259 * structure.
260 */
261 mydata.verify_depth = verify_depth; ...
262 SSL_set_ex_data(ssl, mydata_index, &mydata);
263
264 ...
265 SSL_accept(ssl); /* check of success left out for clarity */
266 if (peer = SSL_get_peer_certificate(ssl))
267 {
268 if (SSL_get_verify_result(ssl) == X509_V_OK)
269 {
270 /* The client sent a certificate which verified OK */
271 }
272 }
273
274=head1 SEE ALSO
275
276L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
277L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
278L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
279L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
280L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
| 104SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
105to which depth certificates in a chain are used during the verification
106procedure. If the certificate chain is longer than allowed, the certificates
107above the limit are ignored. Error messages are generated as if these
108certificates would not be present, most likely a
109X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
110The depth count is "level 0:peer certificate", "level 1: CA certificate",
111"level 2: higher level CA certificate", and so on. Setting the maximum
112depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
113allowing for the peer certificate and additional 9 CA certificates.
114
115The B<verify_callback> function is used to control the behaviour when the
116SSL_VERIFY_PEER flag is set. It must be supplied by the application and
117receives two arguments: B<preverify_ok> indicates, whether the verification of
118the certificate in question was passed (preverify_ok=1) or not
119(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used
120for the certificate chain verification.
121
122The certificate chain is checked starting with the deepest nesting level
123(the root CA certificate) and worked upward to the peer's certificate.
124At each level signatures and issuer attributes are checked. Whenever
125a verification error is found, the error number is stored in B<x509_ctx>
126and B<verify_callback> is called with B<preverify_ok>=0. By applying
127X509_CTX_store_* functions B<verify_callback> can locate the certificate
128in question and perform additional steps (see EXAMPLES). If no error is
129found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
130before advancing to the next level.
131
132The return value of B<verify_callback> controls the strategy of the further
133verification process. If B<verify_callback> returns 0, the verification
134process is immediately stopped with "verification failed" state. If
135SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
136the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
137the verification process is continued. If B<verify_callback> always returns
1381, the TLS/SSL handshake will never be terminated because of this application
139experiencing a verification failure. The calling process can however
140retrieve the error code of the last verification error using
141L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its
142own error storage managed by B<verify_callback>.
143
144If no B<verify_callback> is specified, the default callback will be used.
145Its return value is identical to B<preverify_ok>, so that any verification
146failure will lead to a termination of the TLS/SSL handshake with an
147alert message, if SSL_VERIFY_PEER is set.
148
149=head1 BUGS
150
151In client mode, it is not checked whether the SSL_VERIFY_PEER flag
152is set, but whether SSL_VERIFY_NONE is not set. This can lead to
153unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not
154used as required (exactly one must be set at any time).
155
156The certificate verification depth set with SSL[_CTX]_verify_depth()
157stops the verification at a certain depth. The error message produced
158will be that of an incomplete certificate chain and not
159X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
160
161=head1 RETURN VALUES
162
163The SSL*_set_verify*() functions do not provide diagnostic information.
164
165=head1 EXAMPLES
166
167The following code sequence realizes an example B<verify_callback> function
168that will always continue the TLS/SSL handshake regardless of verification
169failure, if wished. The callback realizes a verification depth limit with
170more informational output.
171
172All verification errors are printed, informations about the certificate chain
173are printed on request.
174The example is realized for a server that does allow but not require client
175certificates.
176
177The example makes use of the ex_data technique to store application data
178into/retrieve application data from the SSL structure
179(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
180L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>).
181
182 ...
183 typedef struct {
184 int verbose_mode;
185 int verify_depth;
186 int always_continue;
187 } mydata_t;
188 int mydata_index;
189 ...
190 static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
191 {
192 char buf[256];
193 X509 *err_cert;
194 int err, depth;
195 SSL *ssl;
196 mydata_t *mydata;
197
198 err_cert = X509_STORE_CTX_get_current_cert(ctx);
199 err = X509_STORE_CTX_get_error(ctx);
200 depth = X509_STORE_CTX_get_error_depth(ctx);
201
202 /*
203 * Retrieve the pointer to the SSL of the connection currently treated
204 * and the application specific data stored into the SSL object.
205 */
206 ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx());
207 mydata = SSL_get_ex_data(ssl, mydata_index);
208
209 X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
210
211 /*
212 * Catch a too long certificate chain. The depth limit set using
213 * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so
214 * that whenever the "depth>verify_depth" condition is met, we
215 * have violated the limit and want to log this error condition.
216 * We must do it here, because the CHAIN_TOO_LONG error would not
217 * be found explicitly; only errors introduced by cutting off the
218 * additional certificates would be logged.
219 */
220 if (depth > mydata->verify_depth) {
221 preverify_ok = 0;
222 err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
223 X509_STORE_CTX_set_error(ctx, err);
224 }
225 if (!preverify_ok) {
226 printf("verify error:num=%d:%s:depth=%d:%s\n", err,
227 X509_verify_cert_error_string(err), depth, buf);
228 }
229 else if (mydata->verbose_mode)
230 {
231 printf("depth=%d:%s\n", depth, buf);
232 }
233
234 /*
235 * At this point, err contains the last verification error. We can use
236 * it for something special
237 */
238 if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)
239 {
240 X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256);
241 printf("issuer= %s\n", buf);
242 }
243
244 if (mydata->always_continue)
245 return 1;
246 else
247 return preverify_ok;
248 }
249 ...
250
251 mydata_t mydata;
252
253 ...
254 mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
255
256 ...
257 SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
258 verify_callback);
259
260 /*
261 * Let the verify_callback catch the verify_depth error so that we get
262 * an appropriate error in the logfile.
263 */
264 SSL_CTX_set_verify_depth(verify_depth + 1);
265
266 /*
267 * Set up the SSL specific data into "mydata" and store it into th SSL
268 * structure.
269 */
270 mydata.verify_depth = verify_depth; ...
271 SSL_set_ex_data(ssl, mydata_index, &mydata);
272
273 ...
274 SSL_accept(ssl); /* check of success left out for clarity */
275 if (peer = SSL_get_peer_certificate(ssl))
276 {
277 if (SSL_get_verify_result(ssl) == X509_V_OK)
278 {
279 /* The client sent a certificate which verified OK */
280 }
281 }
282
283=head1 SEE ALSO
284
285L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
286L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
287L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
288L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
289L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
|