diff options
Diffstat (limited to 'lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3')
| -rw-r--r-- | lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 | 415 |
1 files changed, 0 insertions, 415 deletions
diff --git a/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 b/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 deleted file mode 100644 index 9292f2086ba..00000000000 --- a/lib/libssl/src/doc/ssl/SSL_CTX_set_verify.3 +++ /dev/null @@ -1,415 +0,0 @@ -.\" -.\" $OpenBSD: SSL_CTX_set_verify.3,v 1.2 2014/12/02 14:11:01 jmc Exp $ -.\" -.Dd $Mdocdate: December 2 2014 $ -.Dt SSL_CTX_SET_VERIFY 3 -.Os -.Sh NAME -.Nm SSL_CTX_set_verify , -.Nm SSL_set_verify , -.Nm SSL_CTX_set_verify_depth , -.Nm SSL_set_verify_depth -.Nd set peer certificate verification parameters -.Sh SYNOPSIS -.In openssl/ssl.h -.Ft void -.Fo SSL_CTX_set_verify -.Fa "SSL_CTX *ctx" -.Fa "int mode" -.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" -.Fc -.Ft void -.Fo SSL_set_verify -.Fa "SSL *s" -.Fa "int mode" -.Fa "int (*verify_callback)(int, X509_STORE_CTX *)" -.Fc -.Ft void -.Fn SSL_CTX_set_verify_depth "SSL_CTX *ctx" "int depth" -.Ft void -.Fn SSL_set_verify_depth "SSL *s" "int depth" -.Ft int -.Fn verify_callback "int preverify_ok" "X509_STORE_CTX *x509_ctx" -.Sh DESCRIPTION -.Fn SSL_CTX_set_verify -sets the verification flags for -.Fa ctx -to be -.Fa mode -and -specifies the -.Fa verify_callback -function to be used. -If no callback function shall be specified, the -.Dv NULL -pointer can be used for -.Fa verify_callback . -.Pp -.Fn SSL_set_verify -sets the verification flags for -.Fa ssl -to be -.Fa mode -and specifies the -.Fa verify_callback -function to be used. -If no callback function shall be specified, the -.Dv NULL -pointer can be used for -.Fa verify_callback . -In this case last -.Fa verify_callback -set specifically for this -.Fa ssl -remains. -If no special callback was set before, the default callback for the underlying -.Fa ctx -is used, that was valid at the time -.Fa ssl -was created with -.Xr SSL_new 3 . -.Pp -.Fn SSL_CTX_set_verify_depth -sets the maximum -.Fa depth -for the certificate chain verification that shall be allowed for -.Fa ctx . -(See the -.Sx BUGS -section.) -.Pp -.Fn SSL_set_verify_depth -sets the maximum -.Fa depth -for the certificate chain verification that shall be allowed for -.Fa ssl . -(See the -.Sx BUGS -section.) -.Sh NOTES -The verification of certificates can be controlled by a set of bitwise ORed -.Fa mode -flags: -.Bl -tag -width Ds -.It Dv SSL_VERIFY_NONE -.Em Server mode: -the server will not send a client certificate request to the client, -so the client will not send a certificate. -.Pp -.Em Client mode: -if not using an anonymous cipher (by default disabled), -the server will send a certificate which will be checked. -The result of the certificate verification process can be checked after the -TLS/SSL handshake using the -.Xr SSL_get_verify_result 3 -function. -The handshake will be continued regardless of the verification result. -.It Dv SSL_VERIFY_PEER -.Em Server mode: -the server sends a client certificate request to the client. -The certificate returned (if any) is checked. -If the verification process fails, -the TLS/SSL handshake is immediately terminated with an alert message -containing the reason for the verification failure. -The behaviour can be controlled by the additional -.Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT -and -.Dv SSL_VERIFY_CLIENT_ONCE -flags. -.Pp -.Em Client mode: -the server certificate is verified. -If the verification process fails, -the TLS/SSL handshake is immediately terminated with an alert message -containing the reason for the verification failure. -If no server certificate is sent, because an anonymous cipher is used, -.Dv SSL_VERIFY_PEER -is ignored. -.It Dv SSL_VERIFY_FAIL_IF_NO_PEER_CERT -.Em Server mode: -if the client did not return a certificate, the TLS/SSL -handshake is immediately terminated with a -.Dq handshake failure -alert. -This flag must be used together with -.Dv SSL_VERIFY_PEER. -.Pp -.Em Client mode: -ignored -.It Dv SSL_VERIFY_CLIENT_ONCE -.Em Server mode: -only request a client certificate on the initial TLS/SSL handshake. -Do not ask for a client certificate again in case of a renegotiation. -This flag must be used together with -.Dv SSL_VERIFY_PEER . -.Pp -.Em Client mode: -ignored -.El -.Pp -Exactly one of the -.Fa mode -flags -.Dv SSL_VERIFY_NONE -and -.Dv SSL_VERIFY_PEER -must be set at any time. -.Pp -The actual verification procedure is performed either using the built-in -verification procedure or using another application provided verification -function set with -.Xr SSL_CTX_set_cert_verify_callback 3 . -The following descriptions apply in the case of the built-in procedure. -An application provided procedure also has access to the verify depth -information and the -.Fa verify_callback Ns () -function, but the way this information is used may be different. -.Pp -.Fn SSL_CTX_set_verify_depth -and -.Fn SSL_set_verify_depth -set the limit up to which depth certificates in a chain are used during the -verification procedure. -If the certificate chain is longer than allowed, -the certificates above the limit are ignored. -Error messages are generated as if these certificates would not be present, -most likely a -.Dv X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY -will be issued. -The depth count is -.Dq level 0: peer certificate , -.Dq level 1: CA certificate , -.Dq level 2: higher level CA certificate , -and so on. -Setting the maximum depth to 2 allows the levels 0, 1, and 2. -The default depth limit is 100, -allowing for the peer certificate and an additional 100 CA certificates. -.Pp -The -.Fa verify_callback -function is used to control the behaviour when the -.Dv SSL_VERIFY_PEER -flag is set. -It must be supplied by the application and receives two arguments: -.Fa preverify_ok -indicates whether the verification of the certificate in question was passed -(preverify_ok=1) or not (preverify_ok=0). -.Fa x509_ctx -is a pointer to the complete context used -for the certificate chain verification. -.Pp -The certificate chain is checked starting with the deepest nesting level -(the root CA certificate) and worked upward to the peer's certificate. -At each level signatures and issuer attributes are checked. -Whenever a verification error is found, the error number is stored in -.Fa x509_ctx -and -.Fa verify_callback -is called with -.Fa preverify_ok -equal to 0. -By applying -.Fn X509_CTX_store_* -functions -.Fa verify_callback -can locate the certificate in question and perform additional steps (see -.Sx EXAMPLES ) . -If no error is found for a certificate, -.Fa verify_callback -is called with -.Fa preverify_ok -equal to 1 before advancing to the next level. -.Pp -The return value of -.Fa verify_callback -controls the strategy of the further verification process. -If -.Fa verify_callback -returns 0, the verification process is immediately stopped with -.Dq verification failed -state. -If -.Dv SSL_VERIFY_PEER -is set, a verification failure alert is sent to the peer and the TLS/SSL -handshake is terminated. -If -.Fa verify_callback -returns 1, the verification process is continued. -If -.Fa verify_callback -always returns 1, -the TLS/SSL handshake will not be terminated with respect to verification -failures and the connection will be established. -The calling process can however retrieve the error code of the last -verification error using -.Xr SSL_get_verify_result 3 -or by maintaining its own error storage managed by -.Fa verify_callback . -.Pp -If no -.Fa verify_callback -is specified, the default callback will be used. -Its return value is identical to -.Fa preverify_ok , -so that any verification -failure will lead to a termination of the TLS/SSL handshake with an -alert message, if -.Dv SSL_VERIFY_PEER -is set. -.Sh RETURN VALUES -The -.Fn SSL*_set_verify* -functions do not provide diagnostic information. -.Sh EXAMPLES -The following code sequence realizes an example -.Fa verify_callback -function that will always continue the TLS/SSL handshake regardless of -verification failure, if wished. -The callback realizes a verification depth limit with more informational output. -.Pp -All verification errors are printed; -information about the certificate chain is printed on request. -The example is realized for a server that does allow but not require client -certificates. -.Pp -The example makes use of the ex_data technique to store application data -into/retrieve application data from the -.Vt SSL -structure (see -.Xr SSL_get_ex_new_index 3 , -.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 ) . -.Bd -literal -\&... - -typedef struct { - int verbose_mode; - int verify_depth; - int always_continue; -} mydata_t; -int mydata_index; -\&... -static int -verify_callback(int preverify_ok, X509_STORE_CTX *ctx) -{ - char buf[256]; - X509 *err_cert; - int err, depth; - SSL *ssl; - mydata_t *mydata; - - err_cert = X509_STORE_CTX_get_current_cert(ctx); - err = X509_STORE_CTX_get_error(ctx); - depth = X509_STORE_CTX_get_error_depth(ctx); - - /* - * Retrieve the pointer to the SSL of the connection currently - * treated * and the application specific data stored into the - * SSL object. - */ - ssl = X509_STORE_CTX_get_ex_data(ctx, - SSL_get_ex_data_X509_STORE_CTX_idx()); - mydata = SSL_get_ex_data(ssl, mydata_index); - - X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256); - - /* - * Catch a too long certificate chain. The depth limit set using - * SSL_CTX_set_verify_depth() is by purpose set to "limit+1" so - * that whenever the "depth>verify_depth" condition is met, we - * have violated the limit and want to log this error condition. - * We must do it here, because the CHAIN_TOO_LONG error would not - * be found explicitly; only errors introduced by cutting off the - * additional certificates would be logged. - */ - if (depth > mydata->verify_depth) { - preverify_ok = 0; - err = X509_V_ERR_CERT_CHAIN_TOO_LONG; - X509_STORE_CTX_set_error(ctx, err); - } - if (!preverify_ok) { - printf("verify error:num=%d:%s:depth=%d:%s\en", err, - X509_verify_cert_error_string(err), depth, buf); - } else if (mydata->verbose_mode) { - printf("depth=%d:%s\en", depth, buf); - } - - /* - * At this point, err contains the last verification error. - * We can use it for something special - */ - if (!preverify_ok && (err == - X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT)) { - X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert), - buf, 256); - printf("issuer= %s\en", buf); - } - - if (mydata->always_continue) - return 1; - else - return preverify_ok; -} -\&... - -mydata_t mydata; - -\&... - -mydata_index = SSL_get_ex_new_index(0, "mydata index", NULL, NULL, NULL); - -\&... - -SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE, - verify_callback); - -/* - * Let the verify_callback catch the verify_depth error so that we get - * an appropriate error in the logfile. - */ -SSL_CTX_set_verify_depth(verify_depth + 1); - -/* - * Set up the SSL specific data into "mydata" and store it into the SSL - * structure. - */ -mydata.verify_depth = verify_depth; ... -SSL_set_ex_data(ssl, mydata_index, &mydata); - -\&... - -SSL_accept(ssl); /* check of success left out for clarity */ -if (peer = SSL_get_peer_certificate(ssl)) { - if (SSL_get_verify_result(ssl) == X509_V_OK) { - /* The client sent a certificate which verified OK */ - } -} -.Ed -.Sh SEE ALSO -.Xr ssl 3 , -.Xr SSL_CTX_get_verify_mode 3 , -.Xr SSL_CTX_load_verify_locations 3 , -.Xr SSL_CTX_set_cert_verify_callback 3 , -.Xr SSL_get_ex_data_X509_STORE_CTX_idx 3 , -.Xr SSL_get_ex_new_index 3 , -.Xr SSL_get_peer_certificate 3 , -.Xr SSL_get_verify_result 3 , -.Xr SSL_new 3 -.Sh BUGS -In client mode, it is not checked whether the -.Dv SSL_VERIFY_PEER -flag is set, but whether -.Dv SSL_VERIFY_NONE -is not set. -This can lead to unexpected behaviour, if the -.Dv SSL_VERIFY_PEER -and -.Dv SSL_VERIFY_NONE -are not used as required (exactly one must be set at any time). -.Pp -The certificate verification depth set with -.Fn SSL[_CTX]_verify_depth -stops the verification at a certain depth. -The error message produced will be that of an incomplete certificate chain and -not -.Dv X509_V_ERR_CERT_CHAIN_TOO_LONG -as may be expected. |