Documentation about ephemeral key exchange

5 files changed, 315 insertions, 5 deletions

diff --git a/doc/ssl/SSL_CTX_set_cipher_list.pod b/doc/ssl/SSL_CTX_set_cipher_list.pod
index 84825fb6f5..0fec568296 100644
--- a/doc/ssl/SSL_CTX_set_cipher_list.pod
+++ b/doc/ssl/SSL_CTX_set_cipher_list.pod
@@ -39,8 +39,9 @@ certificate and key.
 A RSA cipher can only be chosen, when a RSA certificate is available.
 RSA export ciphers with a keylength of 512 bits for the RSA key require
 a temporary 512 bit RSA key, as typically the supplied key has a length
-of 1024 bit. RSA ciphers using EDH need a certificate and key and
-additional DH-parameters.
+of 1024 bit (see
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
+RSA ciphers using EDH need a certificate and key and additional DH-parameters.
 
 A DSA cipher can only be chosen, when a DSA certificate is available.
 DSA ciphers always use DH key exchange and therefore need DH-parameters.
@@ -60,6 +61,8 @@ could be selected and 0 on complete failure.
 
 L<ssl(3)|ssl(3)>, L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,
 L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
 L<ciphers(1)|ciphers(1)>
 
 =cut
diff --git a/doc/ssl/SSL_CTX_set_options.pod b/doc/ssl/SSL_CTX_set_options.pod
index 5eb376eda8..47c1e2de9e 100644
--- a/doc/ssl/SSL_CTX_set_options.pod
+++ b/doc/ssl/SSL_CTX_set_options.pod
@@ -122,11 +122,13 @@ The following B<modifying> options are available:
 
 =item SSL_OP_SINGLE_DH_USE
 
-Always create a new key when using temporary DH parameters.
+Always create a new key when using temporary DH parameters
+(see L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>).
 
 =item SSL_OP_EPHEMERAL_RSA
 
-Also use the temporary RSA key when doing RSA operations.
+Also use ephemeral (temporary) RSA key when doing RSA operations
+(see L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>).
 
 =item SSL_OP_CIPHER_SERVER_PREFERENCE
 
@@ -182,7 +184,9 @@ SSL_CTX_get_options() and SSL_get_options() return the current bitmask.
 
 =head1 SEE ALSO
 
-L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>
+L<ssl(3)|ssl(3)>, L<SSL_new(3)|SSL_new(3)>, L<SSL_clear(3)|SSL_clear(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>
 
 =head1 HISTORY
 
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
diff --git a/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod b/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
new file mode 100644
index 0000000000..2347bc98af
--- /dev/null
+++ b/doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod
@@ -0,0 +1,155 @@
+=pod
+
+=head1 NAME
+
+SSL_CTX_set_tmp_rsa_callback, SSL_CTX_set_tmp_rsa, SSL_CTX_need_tmp_rsa, SSL_set_tmp_rsa_callback, SSL_set_tmp_rsa, SSL_need_tmp_rsa - handle RSA keys for ephemeral key exchange
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ void SSL_CTX_set_tmp_rsa_callback(SSL_CTX *ctx,
+            RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_CTX_set_tmp_rsa(SSL_CTX *ctx, RSA *rsa);
+ long SSL_CTX_need_tmp_rsa(SSL_CTX *ctx);
+
+ void SSL_set_tmp_rsa_callback(SSL_CTX *ctx,
+            RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
+ long SSL_set_tmp_rsa(SSL *ssl, RSA *rsa)
+ long SSL_need_tmp_rsa(SSL *ssl)
+
+ RSA *(*tmp_rsa_callback)(SSL *ssl, int is_export, int keylength));
+
+=head1 DESCRIPTION
+
+SSL_CTX_set_tmp_rsa_callback() sets the callback function for B<ctx> to be
+used when a temporary/ephemeral RSA key is required to B<tmp_rsa_callback>.
+The callback is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be
+B<rsa>. The key is inherited by all B<ssl> objects created from B<ctx>.
+
+SSL_CTX_need_tmp_rsa() returns 1, if a temporay/ephemeral RSA key is needed,
+because a RSA key with a keysize larger than 512 bits is installed.
+
+SSL_set_tmp_rsa_callback() sets the callback only for B<ssl>.
+
+SSL_set_tmp_rsa() sets the key only for B<ssl>.
+
+SSL_need_tmp_rsa() returns 1, if a temporay/ephemeral RSA key is needed,
+because a RSA key with a keysize larger than 512 bits is installed.
+
+These functions apply to SSL/TLS servers only.
+
+=head1 NOTES
+
+When using a cipher with RSA authentication, an ephemeral RSA key exchange
+can take place. In this case the session data are negotiated using the
+ephemeral/temporary RSA key and the RSA key supplied and certified
+by the certificate chain is only used for signing.
+
+Using ephemeral RSA key exchange yields forward secrecy, as the connection
+can only be decrypted, when the RSA key is known. By generating a temporary
+RSA 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) RSA key, as this key was
+only used for signing. The downside is that creating a RSA key is
+computationally expensive. On OpenSSL servers ephemeral RSA key exchange
+is therefore disabled by default and must be explicitly enabled using the
+SSL_OP_EPHEMERAL_RSA option of
+L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, except for certain
+export ciphers.
+
+Under previous export restrictions, ciphers with RSA keys shorter (512 bits)
+than the usual key length of 1024 bits were created. To use these ciphers
+with RSA keys of usual length, an ephemeral key exchange must be performed,
+as the normal (certified) key cannot be used.
+
+An application my either directly specify the key or
+can supply the key via a callback function. The callback approach has
+the advantage, that the callback may generate the key only in case it is
+actually needed. As the generation of a RSA key is however costly, it
+will lead to a significant delay in the handshake procedure.
+Another advantage of the callback function is that it can supply keys
+of different size (e.g. for SSL_OP_EPHEMERAL_RSA usage) while the
+explicit setting of the key is only useful for key size of 512 bits
+to satisfy the export restricted ciphers and does give away key length
+if a longer key would be allowed.
+
+The B<tmp_rsa_callback> is called with the B<keylength> needed and
+the B<is_export> information. The B<is_export> flag is set, when the
+ephemeral RSA key exchange is performed with an export cipher.
+
+=head1 EXAMPLES
+
+Generate temporary RSA keys to prepare ephemeral RSA key exchange. As the
+generation of a RSA key costs a lot of computer time, it is saved for later
+reuse. For demonstration purposes, two keys for 512 bits and 1024 bits
+respectively are generated.
+
+ ...
+ /* Set up ephemeral RSA stuff */
+ RSA *rsa_512 = NULL;
+ RSA *rsa_1024 = NULL;
+ if (prepare_export_in_advance || always_use_ephemeral_rsa) {
+   rsa_512 = RSA_generate_key(512,RSA_F4,NULL,NULL);
+   if (rsa_512 == NULL)
+     evaluate_error_queue();
+ }
+ if (always_use_ephemeral_rsa) {
+   /* Only spend the time to generate the key, if it will actually be
+      needed */
+   rsa_1024 = RSA_generate_key(1024,RSA_F4,NULL,NULL);
+   if (rsa_1024 == NULL)
+     evaluate_error_queue();
+   SSL_CTX_set_options(SSL_OP_EPHEMERAL_RSA);
+ }
+ ...
+
+ RSA *tmp_rsa_callback(SSL *s, int is_export, int keylength)
+ {
+    RSA *rsa_tmp=NULL;
+
+    switch (keylength) {
+    case 512:
+      if (rsa_512)
+        rsa_tmp = rsa_512;
+      else { /* generate on the fly */
+        rsa_tmp = RSA_generate_key(512,RSA_F4,NULL,NULL);
+        rsa_512 = rsa_tmp; /* Remember for later reuse */
+      }
+      break;
+    case 1024:
+      if (rsa_1024)
+        rsa_tmp=rsa_1024;
+      else
+        this_should_never_happen_as_we_are_prepared();
+      break;
+    default:
+      /* Generating a key on the fly is very costly, so use what is there */
+      if (rsa_1024)
+        rsa_tmp=rsa_1024;
+      else
+        rsa_tmp=rsa_512; /* Use at least a shorter key */
+    }
+    return(rsa_tmp);
+ }
+
+=head1 RETURN VALUES
+
+SSL_CTX_set_tmp_rsa_callback() and SSL_set_tmp_rsa_callback() do not return
+diagnostic output.
+
+SSL_CTX_set_tmp_rsa() and SSL_set_tmp_rsa() do return 1 on success and 0
+on failure. Check the error queue to find out the reason of failure.
+
+SSL_CTX_need_tmp_rsa() and SSL_need_tmp_rsa() return 1 if a temporary
+RSA key is needed and 0 otherwise.
+
+=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)>
+
+=cut
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index e5bf61a2ae..2a48b09352 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -670,6 +670,8 @@ L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
 L<SSL_CTX_set_session_id_context(3)|SSL_CTX_set_session_id_context(3)>,
 L<SSL_CTX_set_ssl_version(3)|SSL_CTX_set_ssl_version(3)>,
 L<SSL_CTX_set_timeout(3)|SSL_CTX_set_timeout(3)>,
+L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
+L<SSL_CTX_set_tmp_dh_callback(3)|SSL_CTX_set_tmp_dh_callback(3)>,
 L<SSL_CTX_set_verify(3)|SSL_CTX_set_verify(3)>,
 L<SSL_CTX_use_certificate(3)|SSL_CTX_use_certificate(3)>,
 L<SSL_get_ciphers(3)|SSL_get_ciphers(3)>,