SSL_CTX_set_verify.pod revision 269686
172613Skris=pod 272613Skris 372613Skris=head1 NAME 472613Skris 572613SkrisSSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters 672613Skris 772613Skris=head1 SYNOPSIS 872613Skris 972613Skris #include <openssl/ssl.h> 1072613Skris 1172613Skris void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, 1272613Skris int (*verify_callback)(int, X509_STORE_CTX *)); 1372613Skris void SSL_set_verify(SSL *s, int mode, 1472613Skris int (*verify_callback)(int, X509_STORE_CTX *)); 1572613Skris void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); 1672613Skris void SSL_set_verify_depth(SSL *s, int depth); 1772613Skris 1872613Skris int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); 1972613Skris 2072613Skris=head1 DESCRIPTION 2172613Skris 2272613SkrisSSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and 2372613Skrisspecifies the B<verify_callback> function to be used. If no callback function 2472613Skrisshall be specified, the NULL pointer can be used for B<verify_callback>. 2572613Skris 2672613SkrisSSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and 2772613Skrisspecifies the B<verify_callback> function to be used. If no callback function 2872613Skrisshall be specified, the NULL pointer can be used for B<verify_callback>. In 2972613Skristhis case last B<verify_callback> set specifically for this B<ssl> remains. If 3072613Skrisno special B<callback> was set before, the default callback for the underlying 31194206SsimonB<ctx> is used, that was valid at the time B<ssl> was created with 3272613SkrisL<SSL_new(3)|SSL_new(3)>. 3372613Skris 3472613SkrisSSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain 3572613Skrisverification that shall be allowed for B<ctx>. (See the BUGS section.) 3672613Skris 3772613SkrisSSL_set_verify_depth() sets the maximum B<depth> for the certificate chain 3872613Skrisverification that shall be allowed for B<ssl>. (See the BUGS section.) 3972613Skris 4072613Skris=head1 NOTES 4172613Skris 4272613SkrisThe verification of certificates can be controlled by a set of logically 4372613Skrisor'ed B<mode> flags: 4472613Skris 4572613Skris=over 4 4672613Skris 4772613Skris=item SSL_VERIFY_NONE 4872613Skris 4972613SkrisB<Server mode:> the server will not send a client certificate request to the 5072613Skrisclient, so the client will not send a certificate. 5172613Skris 5272613SkrisB<Client mode:> if not using an anonymous cipher (by default disabled), the 5372613Skrisserver will send a certificate which will be checked. The result of the 5472613Skriscertificate verification process can be checked after the TLS/SSL handshake 5572613Skrisusing the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function. 5672613SkrisThe handshake will be continued regardless of the verification result. 5772613Skris 5872613Skris=item SSL_VERIFY_PEER 5972613Skris 6072613SkrisB<Server mode:> the server sends a client certificate request to the client. 6172613SkrisThe certificate returned (if any) is checked. If the verification process 6289837Skrisfails, the TLS/SSL handshake is 6372613Skrisimmediately terminated with an alert message containing the reason for 6472613Skristhe verification failure. 6572613SkrisThe behaviour can be controlled by the additional 6672613SkrisSSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. 6772613Skris 6872613SkrisB<Client mode:> the server certificate is verified. If the verification process 6989837Skrisfails, the TLS/SSL handshake is 7072613Skrisimmediately terminated with an alert message containing the reason for 7172613Skristhe verification failure. If no server certificate is sent, because an 7272613Skrisanonymous cipher is used, SSL_VERIFY_PEER is ignored. 7372613Skris 7472613Skris=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT 7572613Skris 7672613SkrisB<Server mode:> if the client did not return a certificate, the TLS/SSL 7772613Skrishandshake is immediately terminated with a "handshake failure" alert. 7872613SkrisThis flag must be used together with SSL_VERIFY_PEER. 7972613Skris 8072613SkrisB<Client mode:> ignored 8172613Skris 8272613Skris=item SSL_VERIFY_CLIENT_ONCE 8372613Skris 8472613SkrisB<Server mode:> only request a client certificate on the initial TLS/SSL 8572613Skrishandshake. Do not ask for a client certificate again in case of a 8672613Skrisrenegotiation. This flag must be used together with SSL_VERIFY_PEER. 8772613Skris 8872613SkrisB<Client mode:> ignored 8972613Skris 9072613Skris=back 9172613Skris 9272613SkrisExactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be 9372613Skrisset at any time. 9472613Skris 9589837SkrisThe actual verification procedure is performed either using the built-in 9689837Skrisverification procedure or using another application provided verification 9789837Skrisfunction set with 9889837SkrisL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. 9989837SkrisThe following descriptions apply in the case of the built-in procedure. An 10089837Skrisapplication provided procedure also has access to the verify depth information 10189837Skrisand the verify_callback() function, but the way this information is used 10289837Skrismay be different. 10389837Skris 10472613SkrisSSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up 10572613Skristo which depth certificates in a chain are used during the verification 10672613Skrisprocedure. If the certificate chain is longer than allowed, the certificates 10772613Skrisabove the limit are ignored. Error messages are generated as if these 10872613Skriscertificates would not be present, most likely a 10972613SkrisX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. 11072613SkrisThe depth count is "level 0:peer certificate", "level 1: CA certificate", 11172613Skris"level 2: higher level CA certificate", and so on. Setting the maximum 112269686Sjkimdepth to 2 allows the levels 0, 1, and 2. The default depth limit is 100, 113269686Sjkimallowing for the peer certificate and additional 100 CA certificates. 11472613Skris 11572613SkrisThe B<verify_callback> function is used to control the behaviour when the 11672613SkrisSSL_VERIFY_PEER flag is set. It must be supplied by the application and 11772613Skrisreceives two arguments: B<preverify_ok> indicates, whether the verification of 11872613Skristhe certificate in question was passed (preverify_ok=1) or not 11972613Skris(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used 12072613Skrisfor the certificate chain verification. 12172613Skris 12272613SkrisThe certificate chain is checked starting with the deepest nesting level 12372613Skris(the root CA certificate) and worked upward to the peer's certificate. 12472613SkrisAt each level signatures and issuer attributes are checked. Whenever 12572613Skrisa verification error is found, the error number is stored in B<x509_ctx> 12672613Skrisand B<verify_callback> is called with B<preverify_ok>=0. By applying 12772613SkrisX509_CTX_store_* functions B<verify_callback> can locate the certificate 12872613Skrisin question and perform additional steps (see EXAMPLES). If no error is 12972613Skrisfound for a certificate, B<verify_callback> is called with B<preverify_ok>=1 13072613Skrisbefore advancing to the next level. 13172613Skris 13272613SkrisThe return value of B<verify_callback> controls the strategy of the further 13372613Skrisverification process. If B<verify_callback> returns 0, the verification 13472613Skrisprocess is immediately stopped with "verification failed" state. If 13572613SkrisSSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and 13672613Skristhe TLS/SSL handshake is terminated. If B<verify_callback> returns 1, 13772613Skristhe verification process is continued. If B<verify_callback> always returns 138120631Snectar1, the TLS/SSL handshake will not be terminated with respect to verification 139120631Snectarfailures and the connection will be established. The calling process can 140120631Snectarhowever retrieve the error code of the last verification error using 14172613SkrisL<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its 14272613Skrisown error storage managed by B<verify_callback>. 14372613Skris 14472613SkrisIf no B<verify_callback> is specified, the default callback will be used. 14572613SkrisIts return value is identical to B<preverify_ok>, so that any verification 14672613Skrisfailure will lead to a termination of the TLS/SSL handshake with an 14772613Skrisalert message, if SSL_VERIFY_PEER is set. 14872613Skris 14972613Skris=head1 BUGS 15072613Skris 15172613SkrisIn client mode, it is not checked whether the SSL_VERIFY_PEER flag 15272613Skrisis set, but whether SSL_VERIFY_NONE is not set. This can lead to 15372613Skrisunexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not 15472613Skrisused as required (exactly one must be set at any time). 15572613Skris 15672613SkrisThe certificate verification depth set with SSL[_CTX]_verify_depth() 15772613Skrisstops the verification at a certain depth. The error message produced 15872613Skriswill be that of an incomplete certificate chain and not 15972613SkrisX509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. 16072613Skris 16172613Skris=head1 RETURN VALUES 16272613Skris 16372613SkrisThe SSL*_set_verify*() functions do not provide diagnostic information. 16472613Skris 16572613Skris=head1 EXAMPLES 16672613Skris 16772613SkrisThe following code sequence realizes an example B<verify_callback> function 16872613Skristhat will always continue the TLS/SSL handshake regardless of verification 16972613Skrisfailure, if wished. The callback realizes a verification depth limit with 17072613Skrismore informational output. 17172613Skris 172264331SjkimAll verification errors are printed; information about the certificate chain 173264331Sjkimis printed on request. 17472613SkrisThe example is realized for a server that does allow but not require client 17572613Skriscertificates. 17672613Skris 17772613SkrisThe example makes use of the ex_data technique to store application data 17872613Skrisinto/retrieve application data from the SSL structure 17972613Skris(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, 18072613SkrisL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). 18172613Skris 18272613Skris ... 18372613Skris typedef struct { 18472613Skris int verbose_mode; 18572613Skris int verify_depth; 18672613Skris int always_continue; 18772613Skris } mydata_t; 18872613Skris int mydata_index; 18972613Skris ... 19072613Skris static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 19172613Skris { 19272613Skris char buf[256]; 19372613Skris X509 *err_cert; 19472613Skris int err, depth; 19572613Skris SSL *ssl; 19672613Skris mydata_t *mydata; 19772613Skris 19872613Skris err_cert = X509_STORE_CTX_get_current_cert(ctx); 19972613Skris err = X509_STORE_CTX_get_error(ctx); 20072613Skris depth = X509_STORE_CTX_get_error_depth(ctx); 20172613Skris 20272613Skris /* 20372613Skris * Retrieve the pointer to the SSL of the connection currently treated 20472613Skris * and the application specific data stored into the SSL object. 20572613Skris */ 20672613Skris ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); 20772613Skris mydata = SSL_get_ex_data(ssl, mydata_index); 20872613Skris 20972613Skris X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 21072613Skris 21172613Skris /* 21272613Skris * Catch a too long certificate chain. The depth limit set using 21372613Skris * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 21472613Skris * that whenever the "depth>verify_depth" condition is met, we 21572613Skris * have violated the limit and want to log this error condition. 21672613Skris * We must do it here, because the CHAIN_TOO_LONG error would not 21772613Skris * be found explicitly; only errors introduced by cutting off the 21872613Skris * additional certificates would be logged. 21972613Skris */ 22072613Skris if (depth > mydata->verify_depth) { 22172613Skris preverify_ok = 0; 22272613Skris err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 22372613Skris X509_STORE_CTX_set_error(ctx, err); 22472613Skris } 22572613Skris if (!preverify_ok) { 22672613Skris printf("verify error:num=%d:%s:depth=%d:%s\n", err, 22772613Skris X509_verify_cert_error_string(err), depth, buf); 22872613Skris } 22972613Skris else if (mydata->verbose_mode) 23072613Skris { 23172613Skris printf("depth=%d:%s\n", depth, buf); 23272613Skris } 23372613Skris 23472613Skris /* 23572613Skris * At this point, err contains the last verification error. We can use 23672613Skris * it for something special 23772613Skris */ 238109998Smarkm if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) 23972613Skris { 24072613Skris X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); 24172613Skris printf("issuer= %s\n", buf); 24272613Skris } 24372613Skris 24472613Skris if (mydata->always_continue) 24572613Skris return 1; 24672613Skris else 24772613Skris return preverify_ok; 24872613Skris } 24972613Skris ... 25072613Skris 25172613Skris mydata_t mydata; 25272613Skris 25372613Skris ... 25472613Skris mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 25572613Skris 25672613Skris ... 25772613Skris SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, 25872613Skris verify_callback); 25972613Skris 26072613Skris /* 26172613Skris * Let the verify_callback catch the verify_depth error so that we get 26272613Skris * an appropriate error in the logfile. 26372613Skris */ 26472613Skris SSL_CTX_set_verify_depth(verify_depth + 1); 26572613Skris 26672613Skris /* 26772613Skris * Set up the SSL specific data into "mydata" and store it into th SSL 26872613Skris * structure. 26972613Skris */ 27072613Skris mydata.verify_depth = verify_depth; ... 27172613Skris SSL_set_ex_data(ssl, mydata_index, &mydata); 27272613Skris 27372613Skris ... 27472613Skris SSL_accept(ssl); /* check of success left out for clarity */ 27572613Skris if (peer = SSL_get_peer_certificate(ssl)) 27672613Skris { 27772613Skris if (SSL_get_verify_result(ssl) == X509_V_OK) 27872613Skris { 27972613Skris /* The client sent a certificate which verified OK */ 28072613Skris } 28172613Skris } 28272613Skris 28372613Skris=head1 SEE ALSO 28472613Skris 28572613SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, 28672613SkrisL<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, 28772613SkrisL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 28872613SkrisL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, 28972613SkrisL<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, 29089837SkrisL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, 29172613SkrisL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 29272613SkrisL<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> 29372613Skris 29472613Skris=cut 295