Document some SSL DH related functions/macros

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13368)

1 files changed, 68 insertions, 74 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