SSL_CTX_set_verify.pod revision 302408
1170263Sdarrenr=pod 2255332Scy 3255332Scy=head1 NAME 4255332Scy 5255332ScySSL_CTX_set_verify, SSL_set_verify, SSL_CTX_set_verify_depth, SSL_set_verify_depth - set peer certificate verification parameters 6255332Scy 7255332Scy=head1 SYNOPSIS 8145510Sdarrenr 9145510Sdarrenr #include <openssl/ssl.h> 10145510Sdarrenr 11145510Sdarrenr void SSL_CTX_set_verify(SSL_CTX *ctx, int mode, 12170263Sdarrenr int (*verify_callback)(int, X509_STORE_CTX *)); 13170263Sdarrenr void SSL_set_verify(SSL *s, int mode, 14255332Scy int (*verify_callback)(int, X509_STORE_CTX *)); 15255332Scy void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int depth); 16145510Sdarrenr void SSL_set_verify_depth(SSL *s, int depth); 17145510Sdarrenr 18145510Sdarrenr int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx); 19145510Sdarrenr 20255332Scy=head1 DESCRIPTION 21145510Sdarrenr 22145510SdarrenrSSL_CTX_set_verify() sets the verification flags for B<ctx> to be B<mode> and 23145510Sdarrenrspecifies the B<verify_callback> function to be used. If no callback function 24255332Scyshall be specified, the NULL pointer can be used for B<verify_callback>. 25255332Scy 26145510SdarrenrSSL_set_verify() sets the verification flags for B<ssl> to be B<mode> and 27255332Scyspecifies the B<verify_callback> function to be used. If no callback function 28255332Scyshall be specified, the NULL pointer can be used for B<verify_callback>. In 29145510Sdarrenrthis case last B<verify_callback> set specifically for this B<ssl> remains. If 30255332Scyno special B<callback> was set before, the default callback for the underlying 31255332ScyB<ctx> is used, that was valid at the time B<ssl> was created with 32255332ScyL<SSL_new(3)|SSL_new(3)>. 33145510Sdarrenr 34255332ScySSL_CTX_set_verify_depth() sets the maximum B<depth> for the certificate chain 35145510Sdarrenrverification that shall be allowed for B<ctx>. (See the BUGS section.) 36145510Sdarrenr 37145510SdarrenrSSL_set_verify_depth() sets the maximum B<depth> for the certificate chain 38145510Sdarrenrverification that shall be allowed for B<ssl>. (See the BUGS section.) 39145510Sdarrenr 40145510Sdarrenr=head1 NOTES 41145510Sdarrenr 42145510SdarrenrThe verification of certificates can be controlled by a set of logically 43255332Scyor'ed B<mode> flags: 44255332Scy 45145510Sdarrenr=over 4 46255332Scy 47145510Sdarrenr=item SSL_VERIFY_NONE 48145510Sdarrenr 49255332ScyB<Server mode:> the server will not send a client certificate request to the 50145510Sdarrenrclient, so the client will not send a certificate. 51145510Sdarrenr 52145510SdarrenrB<Client mode:> if not using an anonymous cipher (by default disabled), the 53255332Scyserver will send a certificate which will be checked. The result of the 54145510Sdarrenrcertificate verification process can be checked after the TLS/SSL handshake 55145510Sdarrenrusing the L<SSL_get_verify_result(3)|SSL_get_verify_result(3)> function. 56145510SdarrenrThe handshake will be continued regardless of the verification result. 57170263Sdarrenr 58255332Scy=item SSL_VERIFY_PEER 59255332Scy 60145510SdarrenrB<Server mode:> the server sends a client certificate request to the client. 61145510SdarrenrThe certificate returned (if any) is checked. If the verification process 62170263Sdarrenrfails, the TLS/SSL handshake is 63145510Sdarrenrimmediately terminated with an alert message containing the reason for 64145510Sdarrenrthe verification failure. 65170263SdarrenrThe behaviour can be controlled by the additional 66255332ScySSL_VERIFY_FAIL_IF_NO_PEER_CERT and SSL_VERIFY_CLIENT_ONCE flags. 67145510Sdarrenr 68145510SdarrenrB<Client mode:> the server certificate is verified. If the verification process 69145510Sdarrenrfails, the TLS/SSL handshake is 70145510Sdarrenrimmediately terminated with an alert message containing the reason for 71145510Sdarrenrthe verification failure. If no server certificate is sent, because an 72145510Sdarrenranonymous cipher is used, SSL_VERIFY_PEER is ignored. 73145510Sdarrenr 74145510Sdarrenr=item SSL_VERIFY_FAIL_IF_NO_PEER_CERT 75255332Scy 76255332ScyB<Server mode:> if the client did not return a certificate, the TLS/SSL 77255332Scyhandshake is immediately terminated with a "handshake failure" alert. 78255332ScyThis flag must be used together with SSL_VERIFY_PEER. 79145510Sdarrenr 80145510SdarrenrB<Client mode:> ignored 81255332Scy 82145510Sdarrenr=item SSL_VERIFY_CLIENT_ONCE 83255332Scy 84145510SdarrenrB<Server mode:> only request a client certificate on the initial TLS/SSL 85145510Sdarrenrhandshake. Do not ask for a client certificate again in case of a 86255332Scyrenegotiation. This flag must be used together with SSL_VERIFY_PEER. 87255332Scy 88255332ScyB<Client mode:> ignored 89255332Scy 90255332Scy=back 91255332Scy 92255332ScyExactly one of the B<mode> flags SSL_VERIFY_NONE and SSL_VERIFY_PEER must be 93255332Scyset at any time. 94145510Sdarrenr 95170263SdarrenrThe actual verification procedure is performed either using the built-in 96145510Sdarrenrverification procedure or using another application provided verification 97170263Sdarrenrfunction set with 98255332ScyL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>. 99255332ScyThe following descriptions apply in the case of the built-in procedure. An 100255332Scyapplication provided procedure also has access to the verify depth information 101255332Scyand the verify_callback() function, but the way this information is used 102145510Sdarrenrmay be different. 103255332Scy 104255332ScySSL_CTX_set_verify_depth() and SSL_set_verify_depth() set the limit up 105255332Scyto which depth certificates in a chain are used during the verification 106255332Scyprocedure. If the certificate chain is longer than allowed, the certificates 107255332Scyabove the limit are ignored. Error messages are generated as if these 108255332Scycertificates would not be present, most likely a 109255332ScyX509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY will be issued. 110255332ScyThe depth count is "level 0:peer certificate", "level 1: CA certificate", 111145510Sdarrenr"level 2: higher level CA certificate", and so on. Setting the maximum 112170263Sdarrenrdepth to 2 allows the levels 0, 1, and 2. The default depth limit is 100, 113255332Scyallowing for the peer certificate and additional 100 CA certificates. 114145510Sdarrenr 115170263SdarrenrThe B<verify_callback> function is used to control the behaviour when the 116153877SguidoSSL_VERIFY_PEER flag is set. It must be supplied by the application and 117145510Sdarrenrreceives two arguments: B<preverify_ok> indicates, whether the verification of 118145510Sdarrenrthe certificate in question was passed (preverify_ok=1) or not 119145510Sdarrenr(preverify_ok=0). B<x509_ctx> is a pointer to the complete context used 120145510Sdarrenrfor the certificate chain verification. 121145510Sdarrenr 122255332ScyThe certificate chain is checked starting with the deepest nesting level 123255332Scy(the root CA certificate) and worked upward to the peer's certificate. 124170263SdarrenrAt each level signatures and issuer attributes are checked. Whenever 125145510Sdarrenra verification error is found, the error number is stored in B<x509_ctx> 126255332Scyand B<verify_callback> is called with B<preverify_ok>=0. By applying 127145510SdarrenrX509_CTX_store_* functions B<verify_callback> can locate the certificate 128145510Sdarrenrin question and perform additional steps (see EXAMPLES). If no error is 129145510Sdarrenrfound for a certificate, B<verify_callback> is called with B<preverify_ok>=1 130145510Sdarrenrbefore advancing to the next level. 131145510Sdarrenr 132145510SdarrenrThe return value of B<verify_callback> controls the strategy of the further 133255332Scyverification process. If B<verify_callback> returns 0, the verification 134255332Scyprocess is immediately stopped with "verification failed" state. If 135255332ScySSL_VERIFY_PEER is set, a verification failure alert is sent to the peer and 136255332Scythe TLS/SSL handshake is terminated. If B<verify_callback> returns 1, 137255332Scythe verification process is continued. If B<verify_callback> always returns 138255332Scy1, the TLS/SSL handshake will not be terminated with respect to verification 139145510Sdarrenrfailures and the connection will be established. The calling process can 140145510Sdarrenrhowever retrieve the error code of the last verification error using 141145510SdarrenrL<SSL_get_verify_result(3)|SSL_get_verify_result(3)> or by maintaining its 142255332Scyown error storage managed by B<verify_callback>. 143145510Sdarrenr 144145510SdarrenrIf no B<verify_callback> is specified, the default callback will be used. 145145510SdarrenrIts return value is identical to B<preverify_ok>, so that any verification 146145510Sdarrenrfailure will lead to a termination of the TLS/SSL handshake with an 147145510Sdarrenralert message, if SSL_VERIFY_PEER is set. 148145510Sdarrenr 149145510Sdarrenr=head1 BUGS 150145510Sdarrenr 151145510SdarrenrIn client mode, it is not checked whether the SSL_VERIFY_PEER flag 152145510Sdarrenris set, but whether SSL_VERIFY_NONE is not set. This can lead to 153145510Sdarrenrunexpected behaviour, if the SSL_VERIFY_PEER and SSL_VERIFY_NONE are not 154145510Sdarrenrused as required (exactly one must be set at any time). 155170263Sdarrenr 156170263SdarrenrThe certificate verification depth set with SSL[_CTX]_verify_depth() 157170263Sdarrenrstops the verification at a certain depth. The error message produced 158170263Sdarrenrwill be that of an incomplete certificate chain and not 159255332ScyX509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected. 160255332Scy 161255332Scy=head1 RETURN VALUES 162255332Scy 163145510SdarrenrThe SSL*_set_verify*() functions do not provide diagnostic information. 164145510Sdarrenr 165145510Sdarrenr=head1 EXAMPLES 166145510Sdarrenr 167145510SdarrenrThe following code sequence realizes an example B<verify_callback> function 168145510Sdarrenrthat will always continue the TLS/SSL handshake regardless of verification 169255332Scyfailure, if wished. The callback realizes a verification depth limit with 170255332Scymore informational output. 171145510Sdarrenr 172145510SdarrenrAll verification errors are printed; information about the certificate chain 173145510Sdarrenris printed on request. 174145510SdarrenrThe example is realized for a server that does allow but not require client 175145510Sdarrenrcertificates. 176145510Sdarrenr 177145510SdarrenrThe example makes use of the ex_data technique to store application data 178145510Sdarrenrinto/retrieve application data from the SSL structure 179255332Scy(see L<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)>, 180255332ScyL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>). 181145510Sdarrenr 182145510Sdarrenr ... 183255332Scy typedef struct { 184255332Scy int verbose_mode; 185145510Sdarrenr int verify_depth; 186145510Sdarrenr int always_continue; 187255332Scy } mydata_t; 188255332Scy int mydata_index; 189145510Sdarrenr ... 190145510Sdarrenr static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx) 191255332Scy { 192255332Scy char buf[256]; 193255332Scy X509 *err_cert; 194255332Scy int err, depth; 195255332Scy SSL *ssl; 196255332Scy mydata_t *mydata; 197145510Sdarrenr 198145510Sdarrenr err_cert = X509_STORE_CTX_get_current_cert(ctx); 199255332Scy err = X509_STORE_CTX_get_error(ctx); 200255332Scy depth = X509_STORE_CTX_get_error_depth(ctx); 201145510Sdarrenr 202145510Sdarrenr /* 203255332Scy * Retrieve the pointer to the SSL of the connection currently treated 204145510Sdarrenr * and the application specific data stored into the SSL object. 205145510Sdarrenr */ 206145510Sdarrenr ssl = X509_STORE_CTX_get_ex_data(ctx, SSL_get_ex_data_X509_STORE_CTX_idx()); 207145510Sdarrenr mydata = SSL_get_ex_data(ssl, mydata_index); 208145510Sdarrenr 209145510Sdarrenr X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); 210145510Sdarrenr 211145510Sdarrenr /* 212145510Sdarrenr * Catch a too long certificate chain. The depth limit set using 213145510Sdarrenr * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so 214145510Sdarrenr * that whenever the "depth>verify_depth" condition is met, we 215145510Sdarrenr * have violated the limit and want to log this error condition. 216145510Sdarrenr * We must do it here, because the CHAIN_TOO_LONG error would not 217255332Scy * be found explicitly; only errors introduced by cutting off the 218255332Scy * additional certificates would be logged. 219255332Scy */ 220255332Scy if (depth > mydata->verify_depth) { 221255332Scy preverify_ok = 0; 222255332Scy err = X509_V_ERR_CERT_CHAIN_TOO_LONG; 223145510Sdarrenr X509_STORE_CTX_set_error(ctx, err); 224145510Sdarrenr } 225145510Sdarrenr if (!preverify_ok) { 226145510Sdarrenr printf("verify error:num=%d:%s:depth=%d:%s\n", err, 227145510Sdarrenr X509_verify_cert_error_string(err), depth, buf); 228145510Sdarrenr } 229145510Sdarrenr else if (mydata->verbose_mode) 230145510Sdarrenr { 231255332Scy printf("depth=%d:%s\n", depth, buf); 232255332Scy } 233145510Sdarrenr 234145510Sdarrenr /* 235145510Sdarrenr * At this point, err contains the last verification error. We can use 236145510Sdarrenr * it for something special 237145510Sdarrenr */ 238145510Sdarrenr if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) 239145510Sdarrenr { 240145510Sdarrenr X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), buf, 256); 241145510Sdarrenr printf("issuer= %s\n", buf); 242145510Sdarrenr } 243145510Sdarrenr 244145510Sdarrenr if (mydata->always_continue) 245170263Sdarrenr return 1; 246170263Sdarrenr else 247255332Scy return preverify_ok; 248255332Scy } 249255332Scy ... 250255332Scy 251255332Scy mydata_t mydata; 252145510Sdarrenr 253145510Sdarrenr ... 254145510Sdarrenr mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); 255145510Sdarrenr 256170263Sdarrenr ... 257170263Sdarrenr SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, 258145510Sdarrenr verify_callback); 259145510Sdarrenr 260145510Sdarrenr /* 261145510Sdarrenr * Let the verify_callback catch the verify_depth error so that we get 262170263Sdarrenr * an appropriate error in the logfile. 263170263Sdarrenr */ 264255332Scy SSL_CTX_set_verify_depth(verify_depth + 1); 265255332Scy 266145510Sdarrenr /* 267145510Sdarrenr * Set up the SSL specific data into "mydata" and store it into th SSL 268145510Sdarrenr * structure. 269145510Sdarrenr */ 270145510Sdarrenr mydata.verify_depth = verify_depth; ... 271145510Sdarrenr SSL_set_ex_data(ssl, mydata_index, &mydata); 272145510Sdarrenr 273145510Sdarrenr ... 274145510Sdarrenr SSL_accept(ssl); /* check of success left out for clarity */ 275145510Sdarrenr if (peer = SSL_get_peer_certificate(ssl)) 276145510Sdarrenr { 277145510Sdarrenr if (SSL_get_verify_result(ssl) == X509_V_OK) 278145510Sdarrenr { 279145510Sdarrenr /* The client sent a certificate which verified OK */ 280145510Sdarrenr } 281145510Sdarrenr } 282145510Sdarrenr 283255332Scy=head1 SEE ALSO 284255332Scy 285255332ScyL<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, 286255332ScyL<SSL_CTX_get_verify_mode(3)|SSL_CTX_get_verify_mode(3)>, 287255332ScyL<SSL_get_verify_result(3)|SSL_get_verify_result(3)>, 288255332ScyL<SSL_CTX_load_verify_locations(3)|SSL_CTX_load_verify_locations(3)>, 289255332ScyL<SSL_get_peer_certificate(3)|SSL_get_peer_certificate(3)>, 290255332ScyL<SSL_CTX_set_cert_verify_callback(3)|SSL_CTX_set_cert_verify_callback(3)>, 291145510SdarrenrL<SSL_get_ex_data_X509_STORE_CTX_idx(3)|SSL_get_ex_data_X509_STORE_CTX_idx(3)>, 292145510SdarrenrL<SSL_get_ex_new_index(3)|SSL_get_ex_new_index(3)> 293145510Sdarrenr 294145510Sdarrenr=cut 295255332Scy