1.\" $OpenBSD: SSL_CTX_set_verify.3,v 1.7 2018/03/27 17:35:50 schwarze Exp $ 2.\" full merge up to: OpenSSL 9b86974e Aug 17 15:21:33 2015 -0400 3.\" selective merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 4.\" 5.\" This file was written by Lutz Jaenicke <jaenicke@openssl.org>. 6.\" Copyright (c) 2000, 2001, 2002, 2003, 2014 The OpenSSL Project. 7.\" All rights reserved. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 16.\" 2. Redistributions in binary form must reproduce the above copyright 17.\" notice, this list of conditions and the following disclaimer in 18.\" the documentation and/or other materials provided with the 19.\" distribution. 20.\" 21.\" 3. All advertising materials mentioning features or use of this 22.\" software must display the following acknowledgment: 23.\" "This product includes software developed by the OpenSSL Project 24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 25.\" 26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 27.\" endorse or promote products derived from this software without 28.\" prior written permission. For written permission, please contact 29.\" openssl-core@openssl.org. 30.\" 31.\" 5. Products derived from this software may not be called "OpenSSL" 32.\" nor may "OpenSSL" appear in their names without prior written 33.\" permission of the OpenSSL Project. 34.\" 35.\" 6. Redistributions of any form whatsoever must retain the following 36.\" acknowledgment: 37.\" "This product includes software developed by the OpenSSL Project 38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 39.\" 40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 51.\" OF THE POSSIBILITY OF SUCH DAMAGE. 52.\" 53.Dd $Mdocdate: March 27 2018 $ 54.Dt SSL_CTX_SET_VERIFY 3 55.Os 56.Sh NAME 57.Nm SSL_CTX_set_verify , 58.Nm SSL_set_verify , 59.Nm SSL_CTX_set_verify_depth , 60.Nm SSL_set_verify_depth 61.Nd set peer certificate verification parameters 62.Sh SYNOPSIS 63.In openssl/ssl.h 64.Ft void 65.Fo SSL_CTX_set_verify 66.Fa "SSL_CTX *ctx" 67.Fa "int mode" 68.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" 69.Fc 70.Ft void 71.Fo SSL_set_verify 72.Fa "SSL *s" 73.Fa "int mode" 74.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" 75.Fc 76.Ft void 77.Fn SSL_CTX_set_verify_depth "SSL_CTX *ctx" "int depth" 78.Ft void 79.Fn SSL_set_verify_depth "SSL *s" "int depth" 80.Ft int 81.Fn verify_callback "int preverify_ok" "X509_STORE_CTX *x509_ctx" 82.Sh DESCRIPTION 83.Fn SSL_CTX_set_verify 84sets the verification flags for 85.Fa ctx 86to be 87.Fa mode 88and 89specifies the 90.Fa verify_callback 91function to be used. 92If no callback function shall be specified, the 93.Dv NULL 94pointer can be used for 95.Fa verify_callback . 96.Pp 97.Fn SSL_set_verify 98sets the verification flags for 99.Fa ssl 100to be 101.Fa mode 102and specifies the 103.Fa verify_callback 104function to be used. 105If no callback function shall be specified, the 106.Dv NULL 107pointer can be used for 108.Fa verify_callback . 109In this case last 110.Fa verify_callback 111set specifically for this 112.Fa ssl 113remains. 114If no special callback was set before, the default callback for the underlying 115.Fa ctx 116is used, that was valid at the time 117.Fa ssl 118was created with 119.Xr SSL_new 3 . 120Within the callback function, 121.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 122can be called to get the data index of the current 123.Vt SSL 124object that is doing the verification. 125.Pp 126.Fn SSL_CTX_set_verify_depth 127sets the maximum 128.Fa depth 129for the certificate chain verification that shall be allowed for 130.Fa ctx . 131(See the 132.Sx BUGS 133section.) 134.Pp 135.Fn SSL_set_verify_depth 136sets the maximum 137.Fa depth 138for the certificate chain verification that shall be allowed for 139.Fa ssl . 140(See the 141.Sx BUGS 142section.) 143.Pp 144The verification of certificates can be controlled by a set of bitwise ORed 145.Fa mode 146flags: 147.Bl -tag -width Ds 148.It Dv SSL_VERIFY_NONE 149.Em Server mode: 150the server will not send a client certificate request to the client, 151so the client will not send a certificate. 152.Pp 153.Em Client mode: 154if not using an anonymous cipher (by default disabled), 155the server will send a certificate which will be checked. 156The result of the certificate verification process can be checked after the 157TLS/SSL handshake using the 158.Xr SSL_get_verify_result 3 159function. 160The handshake will be continued regardless of the verification result. 161.It Dv SSL_VERIFY_PEER 162.Em Server mode: 163the server sends a client certificate request to the client. 164The certificate returned (if any) is checked. 165If the verification process fails, 166the TLS/SSL handshake is immediately terminated with an alert message 167containing the reason for the verification failure. 168The behaviour can be controlled by the additional 169.Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT 170and 171.Dv SSL_VERIFY_CLIENT_ONCE 172flags. 173.Pp 174.Em Client mode: 175the server certificate is verified. 176If the verification process fails, 177the TLS/SSL handshake is immediately terminated with an alert message 178containing the reason for the verification failure. 179If no server certificate is sent, because an anonymous cipher is used, 180.Dv SSL_VERIFY_PEER 181is ignored. 182.It Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT 183.Em Server mode: 184if the client did not return a certificate, the TLS/SSL 185handshake is immediately terminated with a 186.Dq handshake failure 187alert. 188This flag must be used together with 189.Dv SSL_VERIFY_PEER . 190.Pp 191.Em Client mode: 192ignored 193.It Dv SSL_VERIFY_CLIENT_ONCE 194.Em Server mode: 195only request a client certificate on the initial TLS/SSL handshake. 196Do not ask for a client certificate again in case of a renegotiation. 197This flag must be used together with 198.Dv SSL_VERIFY_PEER . 199.Pp 200.Em Client mode: 201ignored 202.El 203.Pp 204Exactly one of the 205.Fa mode 206flags 207.Dv SSL_VERIFY_NONE 208and 209.Dv SSL_VERIFY_PEER 210must be set at any time. 211.Pp 212The actual verification procedure is performed either using the built-in 213verification procedure or using another application provided verification 214function set with 215.Xr SSL_CTX_set_cert_verify_callback 3 . 216The following descriptions apply in the case of the built-in procedure. 217An application provided procedure also has access to the verify depth 218information and the 219.Fa verify_callback Ns () 220function, but the way this information is used may be different. 221.Pp 222.Fn SSL_CTX_set_verify_depth 223and 224.Fn SSL_set_verify_depth 225set the limit up to which depth certificates in a chain are used during the 226verification procedure. 227If the certificate chain is longer than allowed, 228the certificates above the limit are ignored. 229Error messages are generated as if these certificates would not be present, 230most likely a 231.Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY 232will be issued. 233The depth count is 234.Dq level 0: peer certificate , 235.Dq level 1: CA certificate , 236.Dq level 2: higher level CA certificate , 237and so on. 238Setting the maximum depth to 2 allows the levels 0, 1, and 2. 239The default depth limit is 100, 240allowing for the peer certificate and an additional 100 CA certificates. 241.Pp 242The 243.Fa verify_callback 244function is used to control the behaviour when the 245.Dv SSL_VERIFY_PEER 246flag is set. 247It must be supplied by the application and receives two arguments: 248.Fa preverify_ok 249indicates whether the verification of the certificate in question was passed 250(preverify_ok=1) or not (preverify_ok=0). 251.Fa x509_ctx 252is a pointer to the complete context used 253for the certificate chain verification. 254.Pp 255The certificate chain is checked starting with the deepest nesting level 256(the root CA certificate) and worked upward to the peer's certificate. 257At each level signatures and issuer attributes are checked. 258Whenever a verification error is found, the error number is stored in 259.Fa x509_ctx 260and 261.Fa verify_callback 262is called with 263.Fa preverify_ok 264equal to 0. 265By applying 266.Fn X509_CTX_store_* 267functions 268.Fa verify_callback 269can locate the certificate in question and perform additional steps (see 270.Sx EXAMPLES ) . 271If no error is found for a certificate, 272.Fa verify_callback 273is called with 274.Fa preverify_ok 275equal to 1 before advancing to the next level. 276.Pp 277The return value of 278.Fa verify_callback 279controls the strategy of the further verification process. 280If 281.Fa verify_callback 282returns 0, the verification process is immediately stopped with 283.Dq verification failed 284state. 285If 286.Dv SSL_VERIFY_PEER 287is set, a verification failure alert is sent to the peer and the TLS/SSL 288handshake is terminated. 289If 290.Fa verify_callback 291returns 1, the verification process is continued. 292If 293.Fa verify_callback 294always returns 1, 295the TLS/SSL handshake will not be terminated with respect to verification 296failures and the connection will be established. 297The calling process can however retrieve the error code of the last 298verification error using 299.Xr SSL_get_verify_result 3 300or by maintaining its own error storage managed by 301.Fa verify_callback . 302.Pp 303If no 304.Fa verify_callback 305is specified, the default callback will be used. 306Its return value is identical to 307.Fa preverify_ok , 308so that any verification 309failure will lead to a termination of the TLS/SSL handshake with an 310alert message, if 311.Dv SSL_VERIFY_PEER 312is set. 313.Sh EXAMPLES 314The following code sequence realizes an example 315.Fa verify_callback 316function that will always continue the TLS/SSL handshake regardless of 317verification failure, if wished. 318The callback realizes a verification depth limit with more informational output. 319.Pp 320All verification errors are printed; 321information about the certificate chain is printed on request. 322The example is realized for a server that does allow but not require client 323certificates. 324.Pp 325The example makes use of the ex_data technique to store application data 326into/retrieve application data from the 327.Vt SSL 328structure (see 329.Xr SSL_get_ex_new_index 3 , 330.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ) . 331.Bd -literal 332\&... 333 334typedef struct { 335 int verbose_mode; 336 int verify_depth; 337 int always_continue; 338} mydata_t; 339int mydata_index; 340\&... 341static int 342verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 343{ 344 char buf[256]; 345 X509 *err_cert; 346 int err, depth; 347 SSL *ssl; 348 mydata_t *mydata; 349 350 err_cert = X509_STORE_CTX_get_current_cert(ctx); 351 err = X509_STORE_CTX_get_error(ctx); 352 depth = X509_STORE_CTX_get_error_depth(ctx); 353 354 /* 355 * Retrieve the pointer to the SSL of the connection currently 356 * treated * and the application specific data stored into the 357 * SSL object. 358 */ 359 ssl = X509_STORE_CTX_get_ex_data(ctx, 360 SSL_get_ex_data_X509_STORE_CTX_idx()); 361 mydata = SSL_get_ex_data(ssl, mydata_index); 362 363 X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 364 365 /* 366 * Catch a too long certificate chain. The depth limit set using 367 * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 368 * that whenever the "depth>verify_depth" condition is met, we 369 * have violated the limit and want to log this error condition. 370 * We must do it here, because the CHAIN_TOO_LONG error would not 371 * be found explicitly; only errors introduced by cutting off the 372 * additional certificates would be logged. 373 */ 374 if (depth > mydata->verify_depth) { 375 preverify_ok = 0; 376 err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 377 X509_STORE_CTX_set_error(ctx, err); 378 } 379 if (!preverify_ok) { 380 printf("verify error:num=%d:%s:depth=%d:%s\en", err, 381 X509_verify_cert_error_string(err), depth, buf); 382 } else if (mydata->verbose_mode) { 383 printf("depth=%d:%s\en", depth, buf); 384 } 385 386 /* 387 * At this point, err contains the last verification error. 388 * We can use it for something special 389 */ 390 if (!preverify_ok && (err == 391 X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) { 392 X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), 393 buf, 256); 394 printf("issuer= %s\en", buf); 395 } 396 397 if (mydata->always_continue) 398 return 1; 399 else 400 return preverify_ok; 401} 402\&... 403 404mydata_t mydata; 405 406\&... 407 408mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 409 410\&... 411 412SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, 413 verify_callback); 414 415/* 416 * Let the verify_callback catch the verify_depth error so that we get 417 * an appropriate error in the logfile. 418 */ 419SSL_CTX_set_verify_depth(verify_depth + 1); 420 421/* 422 * Set up the SSL specific data into "mydata" and store it into the SSL 423 * structure. 424 */ 425mydata.verify_depth = verify_depth; ... 426SSL_set_ex_data(ssl, mydata_index, &mydata); 427 428\&... 429 430SSL_accept(ssl); /* check of success left out for clarity */ 431if (peer = SSL_get_peer_certificate(ssl)) { 432 if (SSL_get_verify_result(ssl) == X509_V_OK) { 433 /* The client sent a certificate which verified OK */ 434 } 435} 436.Ed 437.Sh SEE ALSO 438.Xr ssl 3 , 439.Xr SSL_CTX_get_verify_mode 3 , 440.Xr SSL_CTX_load_verify_locations 3 , 441.Xr SSL_CTX_set_cert_verify_callback 3 , 442.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , 443.Xr SSL_get_ex_new_index 3 , 444.Xr SSL_get_peer_certificate 3 , 445.Xr SSL_get_verify_result 3 , 446.Xr SSL_new 3 447.Sh HISTORY 448.Fn SSL_set_verify 449appeared in SSLeay 0.4 or earlier. 450.Fn SSL_CTX_set_verify 451first appeared in SSLeay 0.6.4. 452Both functions have been available since 453.Ox 2.4 . 454.Pp 455.Fn SSL_CTX_set_verify_depth 456and 457.Fn SSL_set_verify_depth 458first appeared in OpenSSL 0.9.3 and have been available since 459.Ox 2.6 . 460.Sh BUGS 461In client mode, it is not checked whether the 462.Dv SSL_VERIFY_PEER 463flag is set, but whether 464.Dv SSL_VERIFY_NONE 465is not set. 466This can lead to unexpected behaviour, if the 467.Dv SSL_VERIFY_PEER 468and 469.Dv SSL_VERIFY_NONE 470are not used as required (exactly one must be set at any time). 471.Pp 472The certificate verification depth set with 473.Fn SSL[_CTX]_verify_depth 474stops the verification at a certain depth. 475The error message produced will be that of an incomplete certificate chain and 476not 477.Dv X509_V_ERR_CERT_CHAIN_TOO_LONG 478as may be expected. 479