lib/libssl/man/SSL_CTX_set_verify.3

   1 .\" $OpenBSD: SSL_CTX_set_verify.3,v 1.6 2018/03/21 17:58:58 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 21 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
  84 sets the verification flags for
  85 .Fa ctx
  86 to be
  87 .Fa mode
  88 and
  89 specifies the
  90 .Fa verify_callback
  91 function to be used.
  92 If no callback function shall be specified, the
  93 .Dv NULL
  94 pointer can be used for
  95 .Fa verify_callback .
  96 .Pp
  97 .Fn SSL_set_verify
  98 sets the verification flags for
  99 .Fa ssl
 100 to be
 101 .Fa mode
 102 and specifies the
 103 .Fa verify_callback
 104 function to be used.
 105 If no callback function shall be specified, the
 106 .Dv NULL
 107 pointer can be used for
 108 .Fa verify_callback .
 109 In this case last
 110 .Fa verify_callback
 111 set specifically for this
 112 .Fa ssl
 113 remains.
 114 If no special callback was set before, the default callback for the underlying
 115 .Fa ctx
 116 is used, that was valid at the time
 117 .Fa ssl
 118 was created with
 119 .Xr SSL_new 3 .
 120 Within the callback function,
 121 .Xr SSL_get_ex_data_X509_STORE_CTX_idx 3
 122 can be called to get the data index of the current
 123 .Vt SSL
 124 object that is doing the verification.
 125 .Pp
 126 .Fn SSL_CTX_set_verify_depth
 127 sets the maximum
 128 .Fa depth
 129 for the certificate chain verification that shall be allowed for
 130 .Fa ctx .
 131 (See the
 132 .Sx BUGS
 133 section.)
 134 .Pp
 135 .Fn SSL_set_verify_depth
 136 sets the maximum
 137 .Fa depth
 138 for the certificate chain verification that shall be allowed for
 139 .Fa ssl .
 140 (See the
 141 .Sx BUGS
 142 section.)
 143 .Pp
 144 The verification of certificates can be controlled by a set of bitwise ORed
 145 .Fa mode
 146 flags:
 147 .Bl -tag -width Ds
 148 .It Dv SSL_VERIFY_NONE
 149 .Em Server mode:
 150 the server will not send a client certificate request to the client,
 151 so the client will not send a certificate.
 152 .Pp
 153 .Em Client mode:
 154 if not using an anonymous cipher (by default disabled),
 155 the server will send a certificate which will be checked.
 156 The result of the certificate verification process can be checked after the
 157 TLS/SSL handshake using the
 158 .Xr SSL_get_verify_result 3
 159 function.
 160 The handshake will be continued regardless of the verification result.
 161 .It Dv SSL_VERIFY_PEER
 162 .Em Server mode:
 163 the server sends a client certificate request to the client.
 164 The certificate returned (if any) is checked.
 165 If the verification process fails,
 166 the TLS/SSL handshake is immediately terminated with an alert message
 167 containing the reason for the verification failure.
 168 The behaviour can be controlled by the additional
 169 .Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT
 170 and
 171 .Dv SSL_VERIFY_CLIENT_ONCE
 172 flags.
 173 .Pp
 174 .Em Client mode:
 175 the server certificate is verified.
 176 If the verification process fails,
 177 the TLS/SSL handshake is immediately terminated with an alert message
 178 containing the reason for the verification failure.
 179 If no server certificate is sent, because an anonymous cipher is used,
 180 .Dv SSL_VERIFY_PEER
 181 is ignored.
 182 .It Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT
 183 .Em Server mode:
 184 if the client did not return a certificate, the TLS/SSL
 185 handshake is immediately terminated with a
 186 .Dq handshake failure
 187 alert.
 188 This flag must be used together with
 189 .Dv SSL_VERIFY_PEER .
 190 .Pp
 191 .Em Client mode:
 192 ignored
 193 .It Dv SSL_VERIFY_CLIENT_ONCE
 194 .Em Server mode:
 195 only request a client certificate on the initial TLS/SSL handshake.
 196 Do not ask for a client certificate again in case of a renegotiation.
 197 This flag must be used together with
 198 .Dv SSL_VERIFY_PEER .
 199 .Pp
 200 .Em Client mode:
 201 ignored
 202 .El
 203 .Pp
 204 Exactly one of the
 205 .Fa mode
 206 flags
 207 .Dv SSL_VERIFY_NONE
 208 and
 209 .Dv SSL_VERIFY_PEER
 210 must be set at any time.
 211 .Pp
 212 The actual verification procedure is performed either using the built-in
 213 verification procedure or using another application provided verification
 214 function set with
 215 .Xr SSL_CTX_set_cert_verify_callback 3 .
 216 The following descriptions apply in the case of the built-in procedure.
 217 An application provided procedure also has access to the verify depth
 218 information and the
 219 .Fa verify_callback Ns ()
 220 function, but the way this information is used may be different.
 221 .Pp
 222 .Fn SSL_CTX_set_verify_depth
 223 and
 224 .Fn SSL_set_verify_depth
 225 set the limit up to which depth certificates in a chain are used during the
 226 verification procedure.
 227 If the certificate chain is longer than allowed,
 228 the certificates above the limit are ignored.
 229 Error messages are generated as if these certificates would not be present,
 230 most likely a
 231 .Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY
 232 will be issued.
 233 The depth count is
 234 .Dq level 0: peer certificate ,
 235 .Dq level 1: CA certificate ,
 236 .Dq level 2: higher level CA certificate ,
 237 and so on.
 238 Setting the maximum depth to 2 allows the levels 0, 1, and 2.
 239 The default depth limit is 100,
 240 allowing for the peer certificate and an additional 100 CA certificates.
 241 .Pp
 242 The
 243 .Fa verify_callback
 244 function is used to control the behaviour when the
 245 .Dv SSL_VERIFY_PEER
 246 flag is set.
 247 It must be supplied by the application and receives two arguments:
 248 .Fa preverify_ok
 249 indicates whether the verification of the certificate in question was passed
 250 (preverify_ok=1) or not (preverify_ok=0).
 251 .Fa x509_ctx
 252 is a pointer to the complete context used
 253 for the certificate chain verification.
 254 .Pp
 255 The certificate chain is checked starting with the deepest nesting level
 256 (the root CA certificate) and worked upward to the peer's certificate.
 257 At each level signatures and issuer attributes are checked.
 258 Whenever a verification error is found, the error number is stored in
 259 .Fa x509_ctx
 260 and
 261 .Fa verify_callback
 262 is called with
 263 .Fa preverify_ok
 264 equal to 0.
 265 By applying
 266 .Fn X509_CTX_store_*
 267 functions
 268 .Fa verify_callback
 269 can locate the certificate in question and perform additional steps (see
 270 .Sx EXAMPLES ) .
 271 If no error is found for a certificate,
 272 .Fa verify_callback
 273 is called with
 274 .Fa preverify_ok
 275 equal to 1 before advancing to the next level.
 276 .Pp
 277 The return value of
 278 .Fa verify_callback
 279 controls the strategy of the further verification process.
 280 If
 281 .Fa verify_callback
 282 returns 0, the verification process is immediately stopped with
 283 .Dq verification failed
 284 state.
 285 If
 286 .Dv SSL_VERIFY_PEER
 287 is set, a verification failure alert is sent to the peer and the TLS/SSL
 288 handshake is terminated.
 289 If
 290 .Fa verify_callback
 291 returns 1, the verification process is continued.
 292 If
 293 .Fa verify_callback
 294 always returns 1,
 295 the TLS/SSL handshake will not be terminated with respect to verification
 296 failures and the connection will be established.
 297 The calling process can however retrieve the error code of the last
 298 verification error using
 299 .Xr SSL_get_verify_result 3
 300 or by maintaining its own error storage managed by
 301 .Fa verify_callback .
 302 .Pp
 303 If no
 304 .Fa verify_callback
 305 is specified, the default callback will be used.
 306 Its return value is identical to
 307 .Fa preverify_ok ,
 308 so that any verification
 309 failure will lead to a termination of the TLS/SSL handshake with an
 310 alert message, if
 311 .Dv SSL_VERIFY_PEER
 312 is set.
 313 .Sh EXAMPLES
 314 The following code sequence realizes an example
 315 .Fa verify_callback
 316 function that will always continue the TLS/SSL handshake regardless of
 317 verification failure, if wished.
 318 The callback realizes a verification depth limit with more informational output.
 319 .Pp
 320 All verification errors are printed;
 321 information about the certificate chain is printed on request.
 322 The example is realized for a server that does allow but not require client
 323 certificates.
 324 .Pp
 325 The example makes use of the ex_data technique to store application data
 326 into/retrieve application data from the
 327 .Vt SSL
 328 structure (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
 334 typedef struct {
 335         int     verbose_mode;
 336         int     verify_depth;
 337         int     always_continue;
 338 } mydata_t;
 339 int mydata_index;
 340 \&...
 341 static int
 342 verify_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
 404 mydata_t mydata;
 405
 406 \&...
 407
 408 mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL);
 409
 410 \&...
 411
 412 SSL_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  */
 419 SSL_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  */
 425 mydata.verify_depth = verify_depth; ...
 426 SSL_set_ex_data(ssl, mydata_index, &mydata);
 427
 428 \&...
 429
 430 SSL_accept(ssl); /* check of success left out for clarity */
 431 if (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_CTX_set_verify
 449 and
 450 .Fn SSL_set_verify
 451 appeared before SSLeay 0.8 and have been available since
 452 .Ox 2.4 .
 453 .Pp
 454 .Fn SSL_CTX_set_verify_depth
 455 and
 456 .Fn SSL_set_verify_depth
 457 first appeared in OpenSSL 0.9.3 and have been available since
 458 .Ox 2.6 .
 459 .Sh BUGS
 460 In client mode, it is not checked whether the
 461 .Dv SSL_VERIFY_PEER
 462 flag is set, but whether
 463 .Dv SSL_VERIFY_NONE
 464 is not set.
 465 This can lead to unexpected behaviour, if the
 466 .Dv SSL_VERIFY_PEER
 467 and
 468 .Dv SSL_VERIFY_NONE
 469 are not used as required (exactly one must be set at any time).
 470 .Pp
 471 The certificate verification depth set with
 472 .Fn SSL[_CTX]_verify_depth
 473 stops the verification at a certain depth.
 474 The error message produced will be that of an incomplete certificate chain and
 475 not
 476 .Dv X509_V_ERR_CERT_CHAIN_TOO_LONG
 477 as may be expected.