1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_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: 
   22: SSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and
   23: specifies the B<verify_callback> function to be used. If no callback function
   24: shall be specified, the NULL pointer can be used for B<verify_callback>.
   25: 
   26: SSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and
   27: specifies the B<verify_callback> function to be used. If no callback function
   28: shall be specified, the NULL pointer can be used for B<verify_callback>. In
   29: this case last B<verify_callback> set specifically for this B<ssl> remains. If
   30: no special B<callback> was set before, the default callback for the underlying
   31: B<ctx> is used, that was valid at the the time B<ssl> was created with
   32: L<SSL_new(3)|SSL_new(3)>.
   33: 
   34: SSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain
   35: verification that shall be allowed for B<ctx>. (See the BUGS section.)
   36: 
   37: SSL_set_verify_depth() sets the maximum B<depth> for the certificate chain
   38: verification that shall be allowed for B<ssl>. (See the BUGS section.)
   39: 
   40: =head1 NOTES
   41: 
   42: The verification of certificates can be controlled by a set of logically
   43: or'ed B<mode> flags:
   44: 
   45: =over 4
   46: 
   47: =item SSL_VERIFY_NONE
   48: 
   49: B<Server mode:> the server will not send a client certificate request to the
   50: client, so the client will not send a certificate.
   51: 
   52: B<Client mode:> if not using an anonymous cipher (by default disabled), the
   53: server will send a certificate which will be checked. The result of the
   54: certificate verification process can be checked after the TLS/SSL handshake
   55: using the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function.
   56: The handshake will be continued regardless of the verification result.
   57: 
   58: =item SSL_VERIFY_PEER
   59: 
   60: B<Server mode:> the server sends a client certificate request to the client.
   61: The certificate returned (if any) is checked. If the verification process
   62: fails, the TLS/SSL handshake is
   63: immediately terminated with an alert message containing the reason for
   64: the verification failure.
   65: The behaviour can be controlled by the additional
   66: SSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags.
   67: 
   68: B<Client mode:> the server certificate is verified. If the verification process
   69: fails, the TLS/SSL handshake is
   70: immediately terminated with an alert message containing the reason for
   71: the verification failure. If no server certificate is sent, because an
   72: anonymous cipher is used, SSL_VERIFY_PEER is ignored.
   73: 
   74: =item SSL_VERIFY_FAIL_IF_NO_PEER_CERT
   75: 
   76: B<Server mode:> if the client did not return a certificate, the TLS/SSL
   77: handshake is immediately terminated with a "handshake failure" alert.
   78: This flag must be used together with SSL_VERIFY_PEER.
   79: 
   80: B<Client mode:> ignored
   81: 
   82: =item SSL_VERIFY_CLIENT_ONCE
   83: 
   84: B<Server mode:> only request a client certificate on the initial TLS/SSL
   85: handshake. Do not ask for a client certificate again in case of a
   86: renegotiation. This flag must be used together with SSL_VERIFY_PEER.
   87: 
   88: B<Client mode:> ignored
   89: 
   90: =back
   91: 
   92: Exactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be
   93: set at any time.
   94: 
   95: The actual verification procedure is performed either using the built-in
   96: verification procedure or using another application provided verification
   97: function set with
   98: L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>.
   99: The following descriptions apply in the case of the built-in procedure. An
  100: application provided procedure also has access to the verify depth information
  101: and the verify_callback() function, but the way this information is used
  102: may be different.
  103: 
  104: SSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up
  105: to which depth certificates in a chain are used during the verification
  106: procedure. If the certificate chain is longer than allowed, the certificates
  107: above the limit are ignored. Error messages are generated as if these
  108: certificates would not be present, most likely a
  109: X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued.
  110: The depth count is "level 0:peer certificate", "level 1: CA certificate",
  111: "level 2: higher level CA certificate", and so on. Setting the maximum
  112: depth to 2 allows the levels 0, 1, and 2. The default depth limit is 9,
  113: allowing for the peer certificate and additional 9 CA certificates.
  114: 
  115: The B<verify_callback> function is used to control the behaviour when the
  116: SSL_VERIFY_PEER flag is set. It must be supplied by the application and
  117: receives two arguments: B<preverify_ok> indicates, whether the verification of
  118: the 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
  120: for the certificate chain verification.
  121: 
  122: The certificate chain is checked starting with the deepest nesting level
  123: (the root CA certificate) and worked upward to the peer's certificate.
  124: At each level signatures and issuer attributes are checked. Whenever
  125: a verification error is found, the error number is stored in B<x509_ctx>
  126: and B<verify_callback> is called with B<preverify_ok>=0. By applying
  127: X509_CTX_store_* functions B<verify_callback> can locate the certificate
  128: in question and perform additional steps (see EXAMPLES). If no error is
  129: found for a certificate, B<verify_callback> is called with B<preverify_ok>=1
  130: before advancing to the next level.
  131: 
  132: The return value of B<verify_callback> controls the strategy of the further
  133: verification process. If B<verify_callback> returns 0, the verification
  134: process is immediately stopped with "verification failed" state. If
  135: SSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and
  136: the TLS/SSL handshake is terminated. If B<verify_callback> returns 1,
  137: the verification process is continued. If B<verify_callback> always returns
  138: 1, the TLS/SSL handshake will not be terminated with respect to verification
  139: failures and the connection will be established. The calling process can
  140: however retrieve the error code of the last verification error using
  141: L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its
  142: own error storage managed by B<verify_callback>.
  143: 
  144: If no B<verify_callback> is specified, the default callback will be used.
  145: Its return value is identical to B<preverify_ok>, so that any verification
  146: failure will lead to a termination of the TLS/SSL handshake with an
  147: alert message, if SSL_VERIFY_PEER is set.
  148: 
  149: =head1 BUGS
  150: 
  151: In client mode, it is not checked whether the SSL_VERIFY_PEER flag
  152: is set, but whether SSL_VERIFY_NONE is not set. This can lead to
  153: unexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not
  154: used as required (exactly one must be set at any time).
  155: 
  156: The certificate verification depth set with SSL[_CTX]_verify_depth()
  157: stops the verification at a certain depth. The error message produced
  158: will be that of an incomplete certificate chain and not
  159: X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.
  160: 
  161: =head1 RETURN VALUES
  162: 
  163: The SSL*_set_verify*() functions do not provide diagnostic information.
  164: 
  165: =head1 EXAMPLES
  166: 
  167: The following code sequence realizes an example B<verify_callback> function
  168: that will always continue the TLS/SSL handshake regardless of verification
  169: failure, if wished. The callback realizes a verification depth limit with
  170: more informational output.
  171: 
  172: All verification errors are printed, informations about the certificate chain
  173: are printed on request.
  174: The example is realized for a server that does allow but not require client
  175: certificates.
  176: 
  177: The example makes use of the ex_data technique to store application data
  178: into/retrieve application data from the SSL structure
  179: (see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>,
  180: L<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: 
  285: L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>,
  286: L<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>,
  287: L<SSL_get_verify_result(3)|SSL_get_verify_result(3)>,
  288: L<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>,
  289: L<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>,
  290: L<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>,
  291: L<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>,
  292: L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>
  293: 
  294: =cut