SSL_CTX_set_verify.pod revision 109998
118099Spst=pod 218099Spst 318099Spst=head1 NAME 418099Spst 518099SpstSSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters 618099Spst 718099Spst=head1 SYNOPSIS 818099Spst 918099Spst #include <openssl/ssl.h> 1018099Spst 1118099Spst void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, 1218099Spst int (*verify_callback)(int, X509_STORE_CTX *)); 1318099Spst void SSL_set_verify(SSL *s, int mode, 1418099Spst int (*verify_callback)(int, X509_STORE_CTX *)); 1518099Spst void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); 1618099Spst void SSL_set_verify_depth(SSL *s, int depth); 1718099Spst 1818099Spst int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); 1918099Spst 2018099Spst=head1 DESCRIPTION 2118099Spst 2218099SpstSSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and 2318099Spstspecifies the B<verify_callback> function to be used. If no callback function 2418099Spstshall be specified, the NULL pointer can be used for B<verify_callback>. 2518099Spst 2618099SpstSSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and 2718099Spstspecifies the B<verify_callback> function to be used. If no callback function 2818099Spstshall be specified, the NULL pointer can be used for B<verify_callback>. In 2918099Spstthis case last B<verify_callback> set specifically for this B<ssl> remains. If 3018099Spstno special B<callback> was set before, the default callback for the underlying 3118099SpstB<ctx> is used, that was valid at the the time B<ssl> was created with 3218099SpstL<SSL_new(3)|SSL_new(3)>. 3318099Spst 3418099SpstSSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain 3518099Spstverification that shall be allowed for B<ctx>. (See the BUGS section.) 3618099Spst 3718099SpstSSL_set_verify_depth() sets the maximum B<depth> for the certificate chain 3818099Spstverification that shall be allowed for B<ssl>. (See the BUGS section.) 3918099Spst 4018099Spst=head1 NOTES 4118099Spst 4218099SpstThe verification of certificates can be controlled by a set of logically 4318099Spstor'ed B<mode> flags: 4418099Spst 4518099Spst=over 4 4618099Spst 4718099Spst=item SSL_VERIFY_NONE 4818099Spst 4918099SpstB<Server mode:> the server will not send a client certificate request to the 5018099Spstclient, so the client will not send a certificate. 5118099Spst 5218099SpstB<Client mode:> if not using an anonymous cipher (by default disabled), the 5318099Spstserver will send a certificate which will be checked. The result of the 5418099Spstcertificate verification process can be checked after the TLS/SSL handshake 5518099Spstusing the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function. 5618099SpstThe handshake will be continued regardless of the verification result. 5718099Spst 5818099Spst=item SSL_VERIFY_PEER 5918099Spst 6018099SpstB<Server mode:> the server sends a client certificate request to the client. 6118099SpstThe certificate returned (if any) is checked. If the verification process 6218099Spstfails, the TLS/SSL handshake is 6318099Spstimmediately terminated with an alert message containing the reason for 6418099Spstthe verification failure. 6518099SpstThe behaviour can be controlled by the additional 6618099SpstSSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. 6718099Spst 6818099SpstB<Client mode:> the server certificate is verified. If the verification process 6918099Spstfails, the TLS/SSL handshake is 7018099Spstimmediately terminated with an alert message containing the reason for 7118099Spstthe verification failure. If no server certificate is sent, because an 7218099Spstanonymous cipher is used, SSL_VERIFY_PEER is ignored. 7318099Spst 7418099Spst=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT 7518099Spst 7618099SpstB<Server mode:> if the client did not return a certificate, the TLS/SSL 7718099Spsthandshake is immediately terminated with a "handshake failure" alert. 7818099SpstThis flag must be used together with SSL_VERIFY_PEER. 7918099Spst 8018099SpstB<Client mode:> ignored 8118099Spst 8218099Spst=item SSL_VERIFY_CLIENT_ONCE 8318099Spst 8418099SpstB<Server mode:> only request a client certificate on the initial TLS/SSL 8518099Spsthandshake. Do not ask for a client certificate again in case of a 8618099Spstrenegotiation. This flag must be used together with SSL_VERIFY_PEER. 8718099Spst 8818099SpstB<Client mode:> ignored 8918099Spst 9018099Spst=back 9118099Spst 9218099SpstExactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be 9318099Spstset at any time. 9418099Spst 9518099SpstThe actual verification procedure is performed either using the built-in 9618099Spstverification procedure or using another application provided verification 9718099Spstfunction set with 9818099SpstL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. 9918099SpstThe following descriptions apply in the case of the built-in procedure. An 10018099Spstapplication provided procedure also has access to the verify depth information 10118099Spstand the verify_callback() function, but the way this information is used 10218099Spstmay be different. 10318099Spst 10418099SpstSSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up 10518099Spstto which depth certificates in a chain are used during the verification 10618099Spstprocedure. If the certificate chain is longer than allowed, the certificates 10718099Spstabove the limit are ignored. Error messages are generated as if these 10818099Spstcertificates would not be present, most likely a 10918099SpstX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. 11018099SpstThe depth count is "level 0:peer certificate", "level 1: CA certificate", 11118099Spst"level 2: higher level CA certificate", and so on. Setting the maximum 11218099Spstdepth to 2 allows the levels 0, 1, and 2. The default depth limit is 9, 11318099Spstallowing for the peer certificate and additional 9 CA certificates. 11418099Spst 11518099SpstThe B<verify_callback> function is used to control the behaviour when the 11618099SpstSSL_VERIFY_PEER flag is set. It must be supplied by the application and 11718099Spstreceives two arguments: B<preverify_ok> indicates, whether the verification of 11818099Spstthe certificate in question was passed (preverify_ok=1) or not 11918099Spst(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used 12018099Spstfor the certificate chain verification. 12118099Spst 12218099SpstThe certificate chain is checked starting with the deepest nesting level 12318099Spst(the root CA certificate) and worked upward to the peer's certificate. 12418099SpstAt each level signatures and issuer attributes are checked. Whenever 12518099Spsta verification error is found, the error number is stored in B<x509_ctx> 12618099Spstand B<verify_callback> is called with B<preverify_ok>=0. By applying 12718099SpstX509_CTX_store_* functions B<verify_callback> can locate the certificate 12818099Spstin question and perform additional steps (see EXAMPLES). If no error is 12918099Spstfound for a certificate, B<verify_callback> is called with B<preverify_ok>=1 13018099Spstbefore advancing to the next level. 13118099Spst 13218099SpstThe return value of B<verify_callback> controls the strategy of the further 13318099Spstverification process. If B<verify_callback> returns 0, the verification 13418099Spstprocess is immediately stopped with "verification failed" state. If 13518099SpstSSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and 13618099Spstthe TLS/SSL handshake is terminated. If B<verify_callback> returns 1, 13718099Spstthe verification process is continued. If B<verify_callback> always returns 13818099Spst1, the TLS/SSL handshake will never be terminated because of this application 13918099Spstexperiencing a verification failure. The calling process can however 14018099Spstretrieve the error code of the last verification error using 14118099SpstL<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its 14218099Spstown error storage managed by B<verify_callback>. 14318099Spst 14418099SpstIf no B<verify_callback> is specified, the default callback will be used. 14518099SpstIts return value is identical to B<preverify_ok>, so that any verification 14618099Spstfailure will lead to a termination of the TLS/SSL handshake with an 14718099Spstalert message, if SSL_VERIFY_PEER is set. 14818099Spst 14918099Spst=head1 BUGS 15018099Spst 15118099SpstIn client mode, it is not checked whether the SSL_VERIFY_PEER flag 15218099Spstis set, but whether SSL_VERIFY_NONE is not set. This can lead to 15318099Spstunexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not 15418099Spstused as required (exactly one must be set at any time). 15518099Spst 15618099SpstThe certificate verification depth set with SSL[_CTX]_verify_depth() 15718099Spststops the verification at a certain depth. The error message produced 15818099Spstwill be that of an incomplete certificate chain and not 15918099SpstX509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. 16018099Spst 16118099Spst=head1 RETURN VALUES 16218099Spst 16318099SpstThe SSL*_set_verify*() functions do not provide diagnostic information. 16418099Spst 16518099Spst=head1 EXAMPLES 16618099Spst 16718099SpstThe following code sequence realizes an example B<verify_callback> function 16818099Spstthat will always continue the TLS/SSL handshake regardless of verification 16918099Spstfailure, if wished. The callback realizes a verification depth limit with 17018099Spstmore informational output. 17118099Spst 17218099SpstAll verification errors are printed, informations about the certificate chain 17318099Spstare printed on request. 17418099SpstThe example is realized for a server that does allow but not require client 17518099Spstcertificates. 17618099Spst 17718099SpstThe example makes use of the ex_data technique to store application data 17818099Spstinto/retrieve application data from the SSL structure 17918099Spst(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, 18018099SpstL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). 18118099Spst 18218099Spst ... 18318099Spst typedef struct { 18418099Spst int verbose_mode; 18518099Spst int verify_depth; 18618099Spst int always_continue; 18718099Spst } mydata_t; 18818099Spst int mydata_index; 18918099Spst ... 19018099Spst static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 19118099Spst { 19218099Spst char buf[256]; 19318099Spst X509 *err_cert; 19418099Spst int err, depth; 19518099Spst SSL *ssl; 19618099Spst mydata_t *mydata; 19718099Spst 198130457Sru err_cert = X509_STORE_CTX_get_current_cert(ctx); 19918099Spst err = X509_STORE_CTX_get_error(ctx); 20018099Spst depth = X509_STORE_CTX_get_error_depth(ctx); 20118099Spst 20218099Spst /* 20318099Spst * Retrieve the pointer to the SSL of the connection currently treated 20418099Spst * and the application specific data stored into the SSL object. 20518099Spst */ 20618099Spst ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); 20718099Spst mydata = SSL_get_ex_data(ssl, mydata_index); 20818099Spst 20918099Spst X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 21018099Spst 21118099Spst /* 21218099Spst * Catch a too long certificate chain. The depth limit set using 21318099Spst * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 21418099Spst * that whenever the "depth>verify_depth" condition is met, we 21518099Spst * have violated the limit and want to log this error condition. 21618099Spst * We must do it here, because the CHAIN_TOO_LONG error would not 21718099Spst * be found explicitly; only errors introduced by cutting off the 21818099Spst * additional certificates would be logged. 21918099Spst */ 22018099Spst if (depth > mydata->verify_depth) { 22118099Spst preverify_ok = 0; 22218099Spst err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 22318099Spst X509_STORE_CTX_set_error(ctx, err); 22418099Spst } 22518099Spst if (!preverify_ok) { 22618099Spst printf("verify error:num=%d:%s:depth=%d:%s\n", err, 22718099Spst X509_verify_cert_error_string(err), depth, buf); 22818099Spst } 22918099Spst else if (mydata->verbose_mode) 23018099Spst { 23118099Spst printf("depth=%d:%s\n", depth, buf); 23218099Spst } 23318099Spst 23418099Spst /* 23518099Spst * At this point, err contains the last verification error. We can use 23618099Spst * it for something special 23718099Spst */ 23818099Spst if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) 23918099Spst { 24018099Spst X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); 24118099Spst printf("issuer= %s\n", buf); 24218099Spst } 24318099Spst 24418099Spst if (mydata->always_continue) 24518099Spst return 1; 24618099Spst else 24718099Spst return preverify_ok; 24818099Spst } 24918099Spst ... 25018099Spst 25118099Spst mydata_t mydata; 25218099Spst 25318099Spst ... 25418099Spst mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 25518099Spst 25618099Spst ... 25718099Spst SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, 25818099Spst verify_callback); 25918099Spst 26018099Spst /* 26118099Spst * Let the verify_callback catch the verify_depth error so that we get 26218099Spst * an appropriate error in the logfile. 26318099Spst */ 26418099Spst SSL_CTX_set_verify_depth(verify_depth + 1); 26518099Spst 26618099Spst /* 26718099Spst * Set up the SSL specific data into "mydata" and store it into th SSL 26818099Spst * structure. 26918099Spst */ 27018099Spst mydata.verify_depth = verify_depth; ... 27118099Spst SSL_set_ex_data(ssl, mydata_index, &mydata); 27218099Spst 27318099Spst ... 27418099Spst SSL_accept(ssl); /* check of success left out for clarity */ 27518099Spst if (peer = SSL_get_peer_certificate(ssl)) 27618099Spst { 27718099Spst if (SSL_get_verify_result(ssl) == X509_V_OK) 27818099Spst { 27918099Spst /* The client sent a certificate which verified OK */ 28018099Spst } 28118099Spst } 28218099Spst 28318099Spst=head1 SEE ALSO 28418099Spst 28518099SpstL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, 28618099SpstL<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, 28718099SpstL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 28818099SpstL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, 28918099SpstL<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, 29018099SpstL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, 29118099SpstL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 29218099SpstL<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> 29318099Spst 29418099Spst=cut 29518099Spst