lib/libssl/man/SSL_CTX_set_verify.3

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