diff options
Diffstat (limited to 'openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod')
-rw-r--r-- | openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 170 |
1 files changed, 170 insertions, 0 deletions
diff --git a/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod new file mode 100644 index 000000000..29d1f8a6f --- /dev/null +++ b/openssl/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod @@ -0,0 +1,170 @@ +=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 parameters 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. +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 +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 always generate a new +DH key during the negotiation, when the DH parameters are supplied via +callback and/or when the SSL_OP_SINGLE_DH_USE option of +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will +immediately create a DH key, when DH parameters are supplied via +SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case, +it may happen that a key is generated on initialization without later +being needed, while on the other hand the computer time during the +negotiation is being saved. + +If "strong" primes were used to generate the DH parameters, it is not strictly +necessary to generate a new key for each handshake but it does improve forward +secrecy. If it is not assured, that "strong" primes were used (see especially +the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used +in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE +has an impact on the computer time needed during negotiation, but it is not +very large, so application authors/users should consider to always enable +this option. + +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<dhparam(1)|dhparam(1)> application. In order to reduce the computer +time needed for this generation, it is possible to use DSA parameters +instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE +is mandatory. + +Application authors may compile in DH parameters. Files dh512.pem, +dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current +version of the OpenSSL distribution contain the 'SKIP' DH parameters, +which use safe primes and were generated verifiably pseudo-randomly. +These files can be converted into C code using the B<-C> option of the +L<dhparam(1)|dhparam(1)> application. +Authors may also generate their own set of parameters using +L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were +generated. The generation of DH parameters during installation is therefore +recommended. + +An application may 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_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, +L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, +L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> + +=cut |