1 files changed, 146 insertions, 0 deletions
diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
new file mode 100644
index 0000000000..7ea4514a19
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -0,0 +1,146 @@
+=pod
+
+=head1 NAME
+
+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
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
+            DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
+
+ void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
+            DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_set_tmp_dh(SSL *ssl, DH *dh)
+
+ DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
+
+=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>.
+
+SSL_set_tmp_dh() sets the paramters only for B<ssl>.
+
+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
+as anonymous ciphers. In this case 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.
+
+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
+only used for signing.
+
+In order to perform a DH key exchange the server must use a DH group
+(DH parameters) and generate a DH key. The server will automatically
+generate the DH key when required, as it is computationally cheap
+(retrieve a random number). The server will reuse the DH key for further
+connections, unless the SSL_OP_SINGLE_DH_USE option of
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set, in which case
+a new DH key for each negotiation will be generated.
+
+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. Therefore application authors
+should not copy the DH parameters from other applications or the OpenSSL
+example application, if they compile in parameters, but generate their
+own set of parameters using e.g. the openssl L<dhparam(1)|dhparam(1)>
+application with the B<-C> option. An application may also generate
+its own set of DH parameters during the installation procedure on a specific
+host, so that each host uses different parameters.
+
+An application my either directly specify the DH parameters or
+can supply the DH parameters via a callback function. The callback approach
+has the advantage, that the callback may supply DH parameters for different
+key lengths.
+
+The B<tmp_dh_callback> is called with the B<keylength> needed and
+the B<is_export> information. The B<is_export> flag is set, when the
+ephemeral DH key exchange is performed with an export cipher.
+
+=head1 EXAMPLES
+
+Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
+partly left out.)
+
+ ...
+ /* Set up ephemeral DH stuff */
+ DH *dh_512 = NULL;
+ DH *dh_1024 = NULL;
+ FILE *paramfile;
+
+ ...
+ /* "openssl dhparam -out dh_param_512.pem -2 512" */
+ paramfile = fopen("dh_param_512.pem", "r");
+ if (paramfile) {
+   dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+   fclose(paramfile);
+ }
+ /* "openssl dhparam -out dh_param_1024.pem -2 1024" */
+ paramfile = fopen("dh_param_1024.pem", "r");
+ if (paramfile) {
+   dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+   fclose(paramfile);
+ }
+ ...
+
+ /* "openssl dhparam -C -2 512" etc... */
+ DH *get_dh512() { ... }
+ DH *get_dh1024() { ... }
+
+ DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
+ {
+    DH *dh_tmp=NULL;
+
+    switch (keylength) {
+    case 512:
+      if (!dh_512)
+        dh_512 = get_dh512();
+      dh_tmp = dh_512;
+      break;
+    case 1024:
+      if (!dh_1024) 
+        dh_1024 = get_dh1024();
+      dh_tmp = dh_1024;
+      break;
+    default:
+      /* Generating a key on the fly is very costly, so use what is there */
+      setup_dh_parameters_like_above();
+    }
+    return(dh_tmp);
+ }
+
+=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 SEE ALSO
+
+L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
+L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
+
+=cut