diff options
-rw-r--r-- | doc/man3/SSL_CTX_set_tmp_dh_callback.pod | 142 | ||||
-rw-r--r-- | util/missingmacro.txt | 2 | ||||
-rw-r--r-- | util/missingmacro111.txt | 2 | ||||
-rw-r--r-- | util/other.syms | 2 |
4 files changed, 70 insertions, 78 deletions
diff --git a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod index fe159bef1b..ac8dd391b2 100644 --- a/doc/man3/SSL_CTX_set_tmp_dh_callback.pod +++ b/doc/man3/SSL_CTX_set_tmp_dh_callback.pod @@ -2,7 +2,8 @@ =head1 NAME -SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, +SSL_CTX_set_dh_auto, SSL_set_dh_auto, SSL_CTX_set0_tmp_dh_pkey, +SSL_set0_tmp_dh_pkey, SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh, SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral key exchange @@ -10,6 +11,15 @@ SSL_set_tmp_dh_callback, SSL_set_tmp_dh #include <openssl/ssl.h> + long SSL_CTX_set_dh_auto(SSL *s, int onoff); + long SSL_set_dh_auto(SSL *s, int onoff); + int SSL_CTX_set0_tmp_dh_pkey(SSL_CTX *ctx, EVP_PKEY *dhpkey); + int SSL_set0_tmp_dh_pkey(SSL *s, EVP_PKEY *dhpkey); + +Deprecated since OpenSSL 3.0, can be hidden entirely by defining +B<OPENSSL_API_COMPAT> with a suitable version value, see +L<openssl_user_macros(7)>: + void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); @@ -22,33 +32,19 @@ SSL_set_tmp_dh_callback, SSL_set_tmp_dh =head1 DESCRIPTION -SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be -used when a DH parameters are required to B<tmp_dh_callback>. -The callback is inherited by all B<ssl> objects created from B<ctx>. - -SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. -The key is inherited by all B<ssl> objects created from B<ctx>. - -SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. +The functions described on this page are relevant for servers only. -SSL_set_tmp_dh() sets the parameters only for B<ssl>. +Some ciphersuites may use ephemeral Diffie-Hellman (DH) key exchange. In these +cases, the session data is negotiated using the ephemeral/temporary DH key and +the key supplied and certified by the certificate chain is only used for +signing. Anonymous ciphers (without a permanent server key) also use ephemeral +DH keys. -These functions apply to SSL/TLS servers only. - -=head1 NOTES - -When using a cipher with RSA authentication, an ephemeral DH key exchange -can take place. Ciphers with DSA keys always use ephemeral DH keys as well. -In these cases, the session data are negotiated using the -ephemeral/temporary DH key and the key supplied and certified -by the certificate chain is only used for signing. -Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. - -Using ephemeral DH key exchange yields forward secrecy, as the connection -can only be decrypted, when the DH key is known. By generating a temporary +Using ephemeral DH key exchange yields forward secrecy as the connection +can only be decrypted when the DH key is known. By generating a temporary DH key inside the server application that is lost when the application is left, it becomes impossible for an attacker to decrypt past sessions, -even if he gets hold of the normal (certified) key, as this key was +even if they get hold of the normal (certified) key, as this key was only used for signing. In order to perform a DH key exchange the server must use a DH group @@ -56,59 +52,57 @@ In order to perform a DH key exchange the server must use a DH group a new DH key during the negotiation. As generating DH parameters is extremely time consuming, an application -should not generate the parameters on the fly but supply the parameters. -DH parameters can be reused, as the actual key is newly generated during -the negotiation. The risk in reusing DH parameters is that an attacker -may specialize on a very often used DH group. Applications should therefore -generate their own DH parameters during the installation process using the -openssl L<openssl-dhparam(1)> application. This application -guarantees that "strong" primes are used. - -An application may either directly specify the DH parameters or -can supply the DH parameters via a callback function. - -Previous versions of the callback used B<is_export> and B<keylength> -parameters to control parameter generation for export and non-export -cipher suites. Modern servers that do not support export cipher suites -are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use -the callback but ignore B<keylength> and B<is_export> and simply -supply at least 2048-bit parameters in the callback. +should not generate the parameters on the fly. DH parameters can be reused, as +the actual key is newly generated during the negotiation. + +Typically applications should use well know DH parameters that have built-in +support in OpenSSL. The macros SSL_CTX_set_dh_auto() and SSL_set_dh_auto() +configure OpenSSL to use the default built-in DH parameters for the B<SSL_CTX> +and B<SSL> objects respectively. Passing a value of 1 in the I<onoff> parameter +switches the feature on, and passing a value of 0 switches it off. The default +setting is off. + +If "auto" DH parameters are switched on then the parameters will be selected to +be consistent with the size of the key associated with the server's certificate. +If there is no certificate (e.g. for PSK ciphersuites), then it it will be +consistent with the size of the negotiated symmetric cipher key. + +Applications may supply their own DH parameters instead of using the built-in +values. This approach is discouraged and applications should in preference use +the built-in parameter support described above. Applications wishing to supply +their own DH parameters should call SSL_CTX_set0_tmp_dh_pkey() or +SSL_set0_tmp_dh_pkey() to supply the parameters for the B<SSL_CTX> or B<SSL> +respectively. The parameters should be supplied in the I<dhpkey> argument as +an B<EVP_PKEY> containg DH parameters. Ownership of the I<dhpkey> value is +passed to the B<SSL_CTX> or B<SSL> object as a result of this call, and so the +caller should not free it if the function call is succesful. + +The deprecated macros SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do the same +thing as SSL_CTX_set0_tmp_dh_pkey() and SSL_set0_tmp_dh_pkey() except that the +DH parameters are supplied in a B<DH> object instead in the I<dh> argument, and +ownership of the B<DH> object is retained by the application. Applications +should use "auto" parameters instead, or call SSL_CTX_set0_tmp_dh_pkey() or +SSL_set0_tmp_dh_pkey() as appropriate. + +An application may instead specify the DH parameters via a callback function +using the functions SSL_CTX_set_tmp_dh_callback() or SSL_set_tmp_dh_callback() +to set the callback for the B<SSL_CTX> or B<SSL> object respectively. These +functions are deprecated. Applications should instead use "auto" parameters, or +specify the parameters via SSL_CTX_set0_tmp_dh_pkey() or SSL_set0_tmp_dh_pkey() +as appropriate. + +The callback will be invoked during a connection when DH parameters are +required. The B<SSL> object for the current connection is supplied as an +argument. Previous versions of OpenSSL used the B<is_export> and B<keylength> +arguments to control parameter generation for export and non-export +cipher suites. Modern OpenSSL does not support export ciphersuites and so these +arguments are unused and can be ignored by the callback. The callback should +return the parameters to be used in a DH object. Ownership of the DH object is +retained by the application and should later be freed. =head1 RETURN VALUES -SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return -diagnostic output. - -SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 -on failure. Check the error queue to find out the reason of failure. - -=head1 EXAMPLES - -Setup DH parameters with a key length of 2048 bits. (Error handling -partly left out.) - -Command-line parameter generation: - - $ openssl dhparam -out dh_param_2048.pem 2048 - -Code for setting up parameters during server initialization: - - SSL_CTX ctx = SSL_CTX_new(); - - DH *dh_2048 = NULL; - FILE *paramfile = fopen("dh_param_2048.pem", "r"); - - if (paramfile) { - dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); - fclose(paramfile); - } else { - /* Error. */ - } - if (dh_2048 == NULL) - /* Error. */ - if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) - /* Error. */ - ... +All of these functions/macros return 1 for success or 0 on error. =head1 SEE ALSO diff --git a/util/missingmacro.txt b/util/missingmacro.txt index 2b02fef5f5..a24cb8a685 100644 --- a/util/missingmacro.txt +++ b/util/missingmacro.txt @@ -143,8 +143,6 @@ DTLSv1_handle_timeout(3) SSL_num_renegotiations(3) SSL_clear_num_renegotiations(3) SSL_total_renegotiations(3) -SSL_CTX_set_dh_auto(3) -SSL_set_dh_auto(3) SSL_get0_certificate_types(3) SSL_CTX_set1_client_certificate_types(3) SSL_set1_client_certificate_types(3) diff --git a/util/missingmacro111.txt b/util/missingmacro111.txt index 6adf5c6cef..0b6a86e7e3 100644 --- a/util/missingmacro111.txt +++ b/util/missingmacro111.txt @@ -179,8 +179,6 @@ SSL_num_renegotiations(3) SSL_clear_num_renegotiations(3) SSL_total_renegotiations(3) SSL_CTX_set_tmp_ecdh(3) -SSL_CTX_set_dh_auto(3) -SSL_set_dh_auto(3) SSL_set_tmp_ecdh(3) SSL_CTX_get_extra_chain_certs(3) SSL_CTX_get_extra_chain_certs_only(3) diff --git a/util/other.syms b/util/other.syms index aa85ffa26a..43072908ec 100644 --- a/util/other.syms +++ b/util/other.syms @@ -475,6 +475,7 @@ SSL_CTX_set1_sigalgs define SSL_CTX_set1_sigalgs_list define SSL_CTX_set1_verify_cert_store define SSL_CTX_set_current_cert define +SSL_CTX_set_dh_auto define SSL_CTX_set_ecdh_auto define SSL_CTX_set_max_cert_list define SSL_CTX_set_max_pipelines define @@ -548,6 +549,7 @@ SSL_set1_sigalgs define SSL_set1_sigalgs_list define SSL_set1_verify_cert_store define SSL_set_current_cert define +SSL_set_dh_auto define SSL_set_ecdh_auto define SSL_set_max_cert_list define SSL_set_max_pipelines define |