1=pod 2 3=head1 NAME 4 5SSL_get_ex_data_X509_STORE_CTX_idx, 6SSL_CTX_set_verify, SSL_set_verify, 7SSL_CTX_set_verify_depth, SSL_set_verify_depth, 8SSL_verify_cb, 9SSL_verify_client_post_handshake, 10SSL_set_post_handshake_auth, 11SSL_CTX_set_post_handshake_auth 12- set peer certificate verification parameters 13 14=head1 SYNOPSIS 15 16 #include <openssl/ssl.h> 17 18 typedef int (*SSL_verify_cb)(int preverify_ok, X509_STORE_CTX *x509_ctx); 19 20 void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, SSL_verify_cb verify_callback); 21 void SSL_set_verify(SSL *ssl, int mode, SSL_verify_cb verify_callback); 22 SSL_get_ex_data_X509_STORE_CTX_idx(void); 23 24 void SSL_CTX_set_verify_depth(SSL_CTX *ctx, int depth); 25 void SSL_set_verify_depth(SSL *ssl, int depth); 26 27 int SSL_verify_client_post_handshake(SSL *ssl); 28 void SSL_CTX_set_post_handshake_auth(SSL_CTX *ctx, int val); 29 void SSL_set_post_handshake_auth(SSL *ssl, int val); 30 31=head1 DESCRIPTION 32 33SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and 34specifies the B<verify_callback> function to be used. If no callback function 35shall be specified, the NULL pointer can be used for B<verify_callback>. 36 37SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and 38specifies the B<verify_callback> function to be used. If no callback function 39shall be specified, the NULL pointer can be used for B<verify_callback>. In 40this case last B<verify_callback> set specifically for this B<ssl> remains. If 41no special B<callback> was set before, the default callback for the underlying 42B<ctx> is used, that was valid at the time B<ssl> was created with 43L<SSL_new(3)>. Within the callback function, 44B<SSL_get_ex_data_X509_STORE_CTX_idx> can be called to get the data index 45of the current SSL object that is doing the verification. 46 47SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain 48verification that shall be allowed for B<ctx>. 49 50SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain 51verification that shall be allowed for B<ssl>. 52 53SSL_CTX_set_post_handshake_auth() and SSL_set_post_handshake_auth() enable the 54Post-Handshake Authentication extension to be added to the ClientHello such that 55post-handshake authentication can be requested by the server. If B<val> is 0 56then the extension is not sent, otherwise it is. By default the extension is not 57sent. A certificate callback will need to be set via 58SSL_CTX_set_client_cert_cb() if no certificate is provided at initialization. 59 60SSL_verify_client_post_handshake() causes a CertificateRequest message to be 61sent by a server on the given B<ssl> connection. The SSL_VERIFY_PEER flag must 62be set; the SSL_VERIFY_POST_HANDSHAKE flag is optional. 63 64=head1 NOTES 65 66The verification of certificates can be controlled by a set of logically 67or'ed B<mode> flags: 68 69=over 4 70 71=item SSL_VERIFY_NONE 72 73B<Server mode:> the server will not send a client certificate request to the 74client, so the client will not send a certificate. 75 76B<Client mode:> if not using an anonymous cipher (by default disabled), the 77server will send a certificate which will be checked. The result of the 78certificate verification process can be checked after the TLS/SSL handshake 79using the L<SSL_get_verify_result(3)> function. 80The handshake will be continued regardless of the verification result. 81 82=item SSL_VERIFY_PEER 83 84B<Server mode:> the server sends a client certificate request to the client. 85The certificate returned (if any) is checked. If the verification process 86fails, the TLS/SSL handshake is 87immediately terminated with an alert message containing the reason for 88the verification failure. 89The behaviour can be controlled by the additional 90SSL_VERIFY_FAIL_IF_NO_PEER_CERT, SSL_VERIFY_CLIENT_ONCE and 91SSL_VERIFY_POST_HANDSHAKE flags. 92 93B<Client mode:> the server certificate is verified. If the verification process 94fails, the TLS/SSL handshake is 95immediately terminated with an alert message containing the reason for 96the verification failure. If no server certificate is sent, because an 97anonymous cipher is used, SSL_VERIFY_PEER is ignored. 98 99=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT 100 101B<Server mode:> if the client did not return a certificate, the TLS/SSL 102handshake is immediately terminated with a "handshake failure" alert. 103This flag must be used together with SSL_VERIFY_PEER. 104 105B<Client mode:> ignored (see BUGS) 106 107=item SSL_VERIFY_CLIENT_ONCE 108 109B<Server mode:> only request a client certificate once during the 110connection. Do not ask for a client certificate again during 111renegotiation or post-authentication if a certificate was requested 112during the initial handshake. This flag must be used together with 113SSL_VERIFY_PEER. 114 115B<Client mode:> ignored (see BUGS) 116 117=item SSL_VERIFY_POST_HANDSHAKE 118 119B<Server mode:> the server will not send a client certificate request 120during the initial handshake, but will send the request via 121SSL_verify_client_post_handshake(). This allows the SSL_CTX or SSL 122to be configured for post-handshake peer verification before the 123handshake occurs. This flag must be used together with 124SSL_VERIFY_PEER. TLSv1.3 only; no effect on pre-TLSv1.3 connections. 125 126B<Client mode:> ignored (see BUGS) 127 128=back 129 130If the B<mode> is SSL_VERIFY_NONE none of the other flags may be set. 131 132The actual verification procedure is performed either using the built-in 133verification procedure or using another application provided verification 134function set with 135L<SSL_CTX_set_cert_verify_callback(3)>. 136The following descriptions apply in the case of the built-in procedure. An 137application provided procedure also has access to the verify depth information 138and the verify_callback() function, but the way this information is used 139may be different. 140 141SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set a limit on the 142number of certificates between the end-entity and trust-anchor certificates. 143Neither the 144end-entity nor the trust-anchor certificates count against B<depth>. If the 145certificate chain needed to reach a trusted issuer is longer than B<depth+2>, 146X509_V_ERR_CERT_CHAIN_TOO_LONG will be issued. 147The depth count is "level 0:peer certificate", "level 1: CA certificate", 148"level 2: higher level CA certificate", and so on. Setting the maximum 149depth to 2 allows the levels 0, 1, 2 and 3 (0 being the end-entity and 3 the 150trust-anchor). 151The default depth limit is 100, 152allowing for the peer certificate, at most 100 intermediate CA certificates and 153a final trust anchor certificate. 154 155The B<verify_callback> function is used to control the behaviour when the 156SSL_VERIFY_PEER flag is set. It must be supplied by the application and 157receives two arguments: B<preverify_ok> indicates, whether the verification of 158the certificate in question was passed (preverify_ok=1) or not 159(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used 160for the certificate chain verification. 161 162The certificate chain is checked starting with the deepest nesting level 163(the root CA certificate) and worked upward to the peer's certificate. 164At each level signatures and issuer attributes are checked. Whenever 165a verification error is found, the error number is stored in B<x509_ctx> 166and B<verify_callback> is called with B<preverify_ok>=0. By applying 167X509_CTX_store_* functions B<verify_callback> can locate the certificate 168in question and perform additional steps (see EXAMPLES). If no error is 169found for a certificate, B<verify_callback> is called with B<preverify_ok>=1 170before advancing to the next level. 171 172The return value of B<verify_callback> controls the strategy of the further 173verification process. If B<verify_callback> returns 0, the verification 174process is immediately stopped with "verification failed" state. If 175SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and 176the TLS/SSL handshake is terminated. If B<verify_callback> returns 1, 177the verification process is continued. If B<verify_callback> always returns 1781, the TLS/SSL handshake will not be terminated with respect to verification 179failures and the connection will be established. The calling process can 180however retrieve the error code of the last verification error using 181L<SSL_get_verify_result(3)> or by maintaining its 182own error storage managed by B<verify_callback>. 183 184If no B<verify_callback> is specified, the default callback will be used. 185Its return value is identical to B<preverify_ok>, so that any verification 186failure will lead to a termination of the TLS/SSL handshake with an 187alert message, if SSL_VERIFY_PEER is set. 188 189After calling SSL_set_post_handshake_auth(), the client will need to add a 190certificate or certificate callback to its configuration before it can 191successfully authenticate. This must be called before SSL_connect(). 192 193SSL_verify_client_post_handshake() requires that verify flags have been 194previously set, and that a client sent the post-handshake authentication 195extension. When the client returns a certificate the verify callback will be 196invoked. A write operation must take place for the Certificate Request to be 197sent to the client, this can be done with SSL_do_handshake() or SSL_write_ex(). 198Only one certificate request may be outstanding at any time. 199 200When post-handshake authentication occurs, a refreshed NewSessionTicket 201message is sent to the client. 202 203=head1 BUGS 204 205In client mode, it is not checked whether the SSL_VERIFY_PEER flag 206is set, but whether any flags other than SSL_VERIFY_NONE are set. This can 207lead to unexpected behaviour if SSL_VERIFY_PEER and other flags are not used as 208required. 209 210=head1 RETURN VALUES 211 212The SSL*_set_verify*() functions do not provide diagnostic information. 213 214The SSL_verify_client_post_handshake() function returns 1 if the request 215succeeded, and 0 if the request failed. The error stack can be examined 216to determine the failure reason. 217 218=head1 EXAMPLES 219 220The following code sequence realizes an example B<verify_callback> function 221that will always continue the TLS/SSL handshake regardless of verification 222failure, if wished. The callback realizes a verification depth limit with 223more informational output. 224 225All verification errors are printed; information about the certificate chain 226is printed on request. 227The example is realized for a server that does allow but not require client 228certificates. 229 230The example makes use of the ex_data technique to store application data 231into/retrieve application data from the SSL structure 232(see L<CRYPTO_get_ex_new_index(3)>, 233L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>). 234 235 ... 236 typedef struct { 237 int verbose_mode; 238 int verify_depth; 239 int always_continue; 240 } mydata_t; 241 int mydata_index; 242 243 ... 244 static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 245 { 246 char buf[256]; 247 X509 *err_cert; 248 int err, depth; 249 SSL *ssl; 250 mydata_t *mydata; 251 252 err_cert = X509_STORE_CTX_get_current_cert(ctx); 253 err = X509_STORE_CTX_get_error(ctx); 254 depth = X509_STORE_CTX_get_error_depth(ctx); 255 256 /* 257 * Retrieve the pointer to the SSL of the connection currently treated 258 * and the application specific data stored into the SSL object. 259 */ 260 ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); 261 mydata = SSL_get_ex_data(ssl, mydata_index); 262 263 X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 264 265 /* 266 * Catch a too long certificate chain. The depth limit set using 267 * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 268 * that whenever the "depth>verify_depth" condition is met, we 269 * have violated the limit and want to log this error condition. 270 * We must do it here, because the CHAIN_TOO_LONG error would not 271 * be found explicitly; only errors introduced by cutting off the 272 * additional certificates would be logged. 273 */ 274 if (depth > mydata->verify_depth) { 275 preverify_ok = 0; 276 err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 277 X509_STORE_CTX_set_error(ctx, err); 278 } 279 if (!preverify_ok) { 280 printf("verify error:num=%d:%s:depth=%d:%s\n", err, 281 X509_verify_cert_error_string(err), depth, buf); 282 } else if (mydata->verbose_mode) { 283 printf("depth=%d:%s\n", depth, buf); 284 } 285 286 /* 287 * At this point, err contains the last verification error. We can use 288 * it for something special 289 */ 290 if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) { 291 X509_NAME_oneline(X509_get_issuer_name(err_cert), buf, 256); 292 printf("issuer= %s\n", buf); 293 } 294 295 if (mydata->always_continue) 296 return 1; 297 else 298 return preverify_ok; 299 } 300 ... 301 302 mydata_t mydata; 303 304 ... 305 mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 306 307 ... 308 SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER | SSL_VERIFY_CLIENT_ONCE, 309 verify_callback); 310 311 /* 312 * Let the verify_callback catch the verify_depth error so that we get 313 * an appropriate error in the logfile. 314 */ 315 SSL_CTX_set_verify_depth(verify_depth + 1); 316 317 /* 318 * Set up the SSL specific data into "mydata" and store it into th SSL 319 * structure. 320 */ 321 mydata.verify_depth = verify_depth; ... 322 SSL_set_ex_data(ssl, mydata_index, &mydata); 323 324 ... 325 SSL_accept(ssl); /* check of success left out for clarity */ 326 if (peer = SSL_get_peer_certificate(ssl)) { 327 if (SSL_get_verify_result(ssl) == X509_V_OK) { 328 /* The client sent a certificate which verified OK */ 329 } 330 } 331 332=head1 SEE ALSO 333 334L<ssl(7)>, L<SSL_new(3)>, 335L<SSL_CTX_get_verify_mode(3)>, 336L<SSL_get_verify_result(3)>, 337L<SSL_CTX_load_verify_locations(3)>, 338L<SSL_get_peer_certificate(3)>, 339L<SSL_CTX_set_cert_verify_callback(3)>, 340L<SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 341L<SSL_CTX_set_client_cert_cb(3)>, 342L<CRYPTO_get_ex_new_index(3)> 343 344=head1 HISTORY 345 346The SSL_VERIFY_POST_HANDSHAKE option, and the SSL_verify_client_post_handshake() 347and SSL_set_post_handshake_auth() functions were added in OpenSSL 1.1.1. 348 349=head1 COPYRIGHT 350 351Copyright 2000-2019 The OpenSSL Project Authors. All Rights Reserved. 352 353Licensed under the OpenSSL license (the "License"). You may not use 354this file except in compliance with the License. You can obtain a copy 355in the file LICENSE in the source distribution or at 356L<https://www.openssl.org/source/license.html>. 357 358=cut 359