From 4db48ec0bdbad08c6852bea37e0aea5a04329b99 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Lutz=20J=C3=A4nicke?= Date: Sat, 21 Jul 2001 11:02:17 +0000 Subject: [PATCH] Documentation about ephemeral key exchange --- doc/ssl/SSL_CTX_set_cipher_list.pod | 7 +- doc/ssl/SSL_CTX_set_options.pod | 10 +- doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 146 +++++++++++++++++++++ doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod | 155 +++++++++++++++++++++++ doc/ssl/ssl.pod | 2 + 5 files changed, 315 insertions(+), 5 deletions(-) create mode 100644 doc/ssl/SSL_CTX_set_tmp_dh_callback.pod create mode 100644 doc/ssl/SSL_CTX_set_tmp_rsa_callback.pod 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). +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, L, L, +L, +L, L =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 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). =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). =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, L, L +L, L, L, +L, +L =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 + + 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 to be +used when a DH parameters are required to B. +The callback is inherited by all B objects created from B. + +SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B. +The key is inherited by all B objects created from B. + +SSL_set_tmp_dh_callback() sets the callback only for B. + +SSL_set_tmp_dh() sets the paramters only for B. + +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 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 +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 is called with the B needed and +the B information. The B 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, L, +L, +L, L + +=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 + + 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 to be +used when a temporary/ephemeral RSA key is required to B. +The callback is inherited by all B objects created from B. + +SSL_CTX_set_tmp_rsa() sets the temporary/ephemeral RSA key to be used to be +B. The key is inherited by all B objects created from B. + +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_set_tmp_rsa() sets the key only for B. + +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, 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 is called with the B needed and +the B information. The B 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, L, +L, +L + +=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, L, L, L, +L, +L, L, L, L, -- 2.25.1