SSL_CTX_set_verify.pod revision 72613
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 3172613SkrisB<ctx> is used, that was valid at the 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 6272613Skrisfails as indicated by B<verify_callback>, 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 6972613Skrisfails as indicated by B<verify_callback>, 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 9572613SkrisSSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up 9672613Skristo which depth certificates in a chain are used during the verification 9772613Skrisprocedure. If the certificate chain is longer than allowed, the certificates 9872613Skrisabove the limit are ignored. Error messages are generated as if these 9972613Skriscertificates would not be present, most likely a 10072613SkrisX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. 10172613SkrisThe depth count is "level 0:peer certificate", "level 1: CA certificate", 10272613Skris"level 2: higher level CA certificate", and so on. Setting the maximum 10372613Skrisdepth to 2 allows the levels 0, 1, and 2. The default depth limit is 9, 10472613Skrisallowing for the peer certificate and additional 9 CA certificates. 10572613Skris 10672613SkrisThe B<verify_callback> function is used to control the behaviour when the 10772613SkrisSSL_VERIFY_PEER flag is set. It must be supplied by the application and 10872613Skrisreceives two arguments: B<preverify_ok> indicates, whether the verification of 10972613Skristhe certificate in question was passed (preverify_ok=1) or not 11072613Skris(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used 11172613Skrisfor the certificate chain verification. 11272613Skris 11372613SkrisThe certificate chain is checked starting with the deepest nesting level 11472613Skris(the root CA certificate) and worked upward to the peer's certificate. 11572613SkrisAt each level signatures and issuer attributes are checked. Whenever 11672613Skrisa verification error is found, the error number is stored in B<x509_ctx> 11772613Skrisand B<verify_callback> is called with B<preverify_ok>=0. By applying 11872613SkrisX509_CTX_store_* functions B<verify_callback> can locate the certificate 11972613Skrisin question and perform additional steps (see EXAMPLES). If no error is 12072613Skrisfound for a certificate, B<verify_callback> is called with B<preverify_ok>=1 12172613Skrisbefore advancing to the next level. 12272613Skris 12372613SkrisThe return value of B<verify_callback> controls the strategy of the further 12472613Skrisverification process. If B<verify_callback> returns 0, the verification 12572613Skrisprocess is immediately stopped with "verification failed" state. If 12672613SkrisSSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and 12772613Skristhe TLS/SSL handshake is terminated. If B<verify_callback> returns 1, 12872613Skristhe verification process is continued. If B<verify_callback> always returns 12972613Skris1, the TLS/SSL handshake will never be terminated because of this application 13072613Skrisexperiencing a verification failure. The calling process can however 13172613Skrisretrieve the error code of the last verification error using 13272613SkrisL<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its 13372613Skrisown error storage managed by B<verify_callback>. 13472613Skris 13572613SkrisIf no B<verify_callback> is specified, the default callback will be used. 13672613SkrisIts return value is identical to B<preverify_ok>, so that any verification 13772613Skrisfailure will lead to a termination of the TLS/SSL handshake with an 13872613Skrisalert message, if SSL_VERIFY_PEER is set. 13972613Skris 14072613Skris=head1 BUGS 14172613Skris 14272613SkrisIn client mode, it is not checked whether the SSL_VERIFY_PEER flag 14372613Skrisis set, but whether SSL_VERIFY_NONE is not set. This can lead to 14472613Skrisunexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not 14572613Skrisused as required (exactly one must be set at any time). 14672613Skris 14772613SkrisThe certificate verification depth set with SSL[_CTX]_verify_depth() 14872613Skrisstops the verification at a certain depth. The error message produced 14972613Skriswill be that of an incomplete certificate chain and not 15072613SkrisX509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. 15172613Skris 15272613Skris=head1 RETURN VALUES 15372613Skris 15472613SkrisThe SSL*_set_verify*() functions do not provide diagnostic information. 15572613Skris 15672613Skris=head1 EXAMPLES 15772613Skris 15872613SkrisThe following code sequence realizes an example B<verify_callback> function 15972613Skristhat will always continue the TLS/SSL handshake regardless of verification 16072613Skrisfailure, if wished. The callback realizes a verification depth limit with 16172613Skrismore informational output. 16272613Skris 16372613SkrisAll verification errors are printed, informations about the certificate chain 16472613Skrisare printed on request. 16572613SkrisThe example is realized for a server that does allow but not require client 16672613Skriscertificates. 16772613Skris 16872613SkrisThe example makes use of the ex_data technique to store application data 16972613Skrisinto/retrieve application data from the SSL structure 17072613Skris(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, 17172613SkrisL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). 17272613Skris 17372613Skris ... 17472613Skris typedef struct { 17572613Skris int verbose_mode; 17672613Skris int verify_depth; 17772613Skris int always_continue; 17872613Skris } mydata_t; 17972613Skris int mydata_index; 18072613Skris ... 18172613Skris static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 18272613Skris { 18372613Skris char buf[256]; 18472613Skris X509 *err_cert; 18572613Skris int err, depth; 18672613Skris SSL *ssl; 18772613Skris mydata_t *mydata; 18872613Skris 18972613Skris err_cert = X509_STORE_CTX_get_current_cert(ctx); 19072613Skris err = X509_STORE_CTX_get_error(ctx); 19172613Skris depth = X509_STORE_CTX_get_error_depth(ctx); 19272613Skris 19372613Skris /* 19472613Skris * Retrieve the pointer to the SSL of the connection currently treated 19572613Skris * and the application specific data stored into the SSL object. 19672613Skris */ 19772613Skris ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); 19872613Skris mydata = SSL_get_ex_data(ssl, mydata_index); 19972613Skris 20072613Skris X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 20172613Skris 20272613Skris /* 20372613Skris * Catch a too long certificate chain. The depth limit set using 20472613Skris * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 20572613Skris * that whenever the "depth>verify_depth" condition is met, we 20672613Skris * have violated the limit and want to log this error condition. 20772613Skris * We must do it here, because the CHAIN_TOO_LONG error would not 20872613Skris * be found explicitly; only errors introduced by cutting off the 20972613Skris * additional certificates would be logged. 21072613Skris */ 21172613Skris if (depth > mydata->verify_depth) { 21272613Skris preverify_ok = 0; 21372613Skris err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 21472613Skris X509_STORE_CTX_set_error(ctx, err); 21572613Skris } 21672613Skris if (!preverify_ok) { 21772613Skris printf("verify error:num=%d:%s:depth=%d:%s\n", err, 21872613Skris X509_verify_cert_error_string(err), depth, buf); 21972613Skris } 22072613Skris else if (mydata->verbose_mode) 22172613Skris { 22272613Skris printf("depth=%d:%s\n", depth, buf); 22372613Skris } 22472613Skris 22572613Skris /* 22672613Skris * At this point, err contains the last verification error. We can use 22772613Skris * it for something special 22872613Skris */ 22972613Skris if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT) 23072613Skris { 23172613Skris X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); 23272613Skris printf("issuer= %s\n", buf); 23372613Skris } 23472613Skris 23572613Skris if (mydata->always_continue) 23672613Skris return 1; 23772613Skris else 23872613Skris return preverify_ok; 23972613Skris } 24072613Skris ... 24172613Skris 24272613Skris mydata_t mydata; 24372613Skris 24472613Skris ... 24572613Skris mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 24672613Skris 24772613Skris ... 24872613Skris SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, 24972613Skris verify_callback); 25072613Skris 25172613Skris /* 25272613Skris * Let the verify_callback catch the verify_depth error so that we get 25372613Skris * an appropriate error in the logfile. 25472613Skris */ 25572613Skris SSL_CTX_set_verify_depth(verify_depth + 1); 25672613Skris 25772613Skris /* 25872613Skris * Set up the SSL specific data into "mydata" and store it into th SSL 25972613Skris * structure. 26072613Skris */ 26172613Skris mydata.verify_depth = verify_depth; ... 26272613Skris SSL_set_ex_data(ssl, mydata_index, &mydata); 26372613Skris 26472613Skris ... 26572613Skris SSL_accept(ssl); /* check of success left out for clarity */ 26672613Skris if (peer = SSL_get_peer_certificate(ssl)) 26772613Skris { 26872613Skris if (SSL_get_verify_result(ssl) == X509_V_OK) 26972613Skris { 27072613Skris /* The client sent a certificate which verified OK */ 27172613Skris } 27272613Skris } 27372613Skris 27472613Skris=head1 SEE ALSO 27572613Skris 27672613SkrisL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, 27772613SkrisL<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, 27872613SkrisL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 27972613SkrisL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, 28072613SkrisL<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, 28172613SkrisL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 28272613SkrisL<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> 28372613Skris 28472613Skris=cut 285