SSL_CTX_set_tmp_dh_callback.pod revision 89837
189837Skris=pod 289837Skris 389837Skris=head1 NAME 489837Skris 589837SkrisSSL_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 689837Skris 789837Skris=head1 SYNOPSIS 889837Skris 989837Skris #include <openssl/ssl.h> 1089837Skris 1189837Skris void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, 1289837Skris DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 1389837Skris long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); 1489837Skris 1589837Skris void SSL_set_tmp_dh_callback(SSL_CTX *ctx, 1689837Skris DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 1789837Skris long SSL_set_tmp_dh(SSL *ssl, DH *dh) 1889837Skris 1989837Skris DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 2089837Skris 2189837Skris=head1 DESCRIPTION 2289837Skris 2389837SkrisSSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be 2489837Skrisused when a DH parameters are required to B<tmp_dh_callback>. 2589837SkrisThe callback is inherited by all B<ssl> objects created from B<ctx>. 2689837Skris 2789837SkrisSSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. 2889837SkrisThe key is inherited by all B<ssl> objects created from B<ctx>. 2989837Skris 3089837SkrisSSL_set_tmp_dh_callback() sets the callback only for B<ssl>. 3189837Skris 3289837SkrisSSL_set_tmp_dh() sets the parameters only for B<ssl>. 3389837Skris 3489837SkrisThese functions apply to SSL/TLS servers only. 3589837Skris 3689837Skris=head1 NOTES 3789837Skris 3889837SkrisWhen using a cipher with RSA authentication, an ephemeral DH key exchange 3989837Skriscan take place. Ciphers with DSA keys always use ephemeral DH keys as well. 4089837SkrisIn these cases, the session data are negotiated using the 4189837Skrisephemeral/temporary DH key and the key supplied and certified 4289837Skrisby the certificate chain is only used for signing. 4389837SkrisAnonymous ciphers (without a permanent server key) also use ephemeral DH keys. 4489837Skris 4589837SkrisUsing ephemeral DH key exchange yields forward secrecy, as the connection 4689837Skriscan only be decrypted, when the DH key is known. By generating a temporary 4789837SkrisDH key inside the server application that is lost when the application 4889837Skrisis left, it becomes impossible for an attacker to decrypt past sessions, 4989837Skriseven if he gets hold of the normal (certified) key, as this key was 5089837Skrisonly used for signing. 5189837Skris 5289837SkrisIn order to perform a DH key exchange the server must use a DH group 5389837Skris(DH parameters) and generate a DH key. The server will always generate a new 5489837SkrisDH key during the negotiation, when the DH parameters are supplied via 5589837Skriscallback and/or when the SSL_OP_SINGLE_DH_USE option of 5689837SkrisL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will 5789837Skrisimmediately create a DH key, when DH parameters are supplied via 5889837SkrisSSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case, 5989837Skrisit may happen that a key is generated on initialization without later 6089837Skrisbeing needed, while on the other hand the computer time during the 6189837Skrisnegotiation is being saved. 6289837Skris 6389837SkrisIf "strong" primes were used to generate the DH parameters, it is not strictly 6489837Skrisnecessary to generate a new key for each handshake but it does improve forward 6589837Skrissecrecy. If it is not assured, that "strong" primes were used (see especially 6689837Skristhe section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used 6789837Skrisin order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE 6889837Skrishas an impact on the computer time needed during negotiation, but it is not 6989837Skrisvery large, so application authors/users should consider to always enable 7089837Skristhis option. 7189837Skris 7289837SkrisAs generating DH parameters is extremely time consuming, an application 7389837Skrisshould not generate the parameters on the fly but supply the parameters. 7489837SkrisDH parameters can be reused, as the actual key is newly generated during 7589837Skristhe negotiation. The risk in reusing DH parameters is that an attacker 7689837Skrismay specialize on a very often used DH group. Applications should therefore 7789837Skrisgenerate their own DH parameters during the installation process using the 7889837Skrisopenssl L<dhparam(1)|dhparam(1)> application. In order to reduce the computer 7989837Skristime needed for this generation, it is possible to use DSA parameters 8089837Skrisinstead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE 8189837Skrisis mandatory. 8289837Skris 8389837SkrisApplication authors may compile in DH parameters. Files dh512.pem, 8489837Skrisdh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current 8589837Skrisversion of the OpenSSL distribution contain the 'SKIP' DH parameters, 8689837Skriswhich use safe primes and were generated verifiably pseudo-randomly. 8789837SkrisThese files can be converted into C code using the B<-C> option of the 8889837SkrisL<dhparam(1)|dhparam(1)> application. 8989837SkrisAuthors may also generate their own set of parameters using 9089837SkrisL<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were 9189837Skrisgenerated. The generation of DH parameters during installation is therefore 9289837Skrisrecommended. 9389837Skris 9489837SkrisAn application may either directly specify the DH parameters or 9589837Skriscan supply the DH parameters via a callback function. The callback approach 9689837Skrishas the advantage, that the callback may supply DH parameters for different 9789837Skriskey lengths. 9889837Skris 9989837SkrisThe B<tmp_dh_callback> is called with the B<keylength> needed and 10089837Skristhe B<is_export> information. The B<is_export> flag is set, when the 10189837Skrisephemeral DH key exchange is performed with an export cipher. 10289837Skris 10389837Skris=head1 EXAMPLES 10489837Skris 10589837SkrisHandle DH parameters for key lengths of 512 and 1024 bits. (Error handling 10689837Skrispartly left out.) 10789837Skris 10889837Skris ... 10989837Skris /* Set up ephemeral DH stuff */ 11089837Skris DH *dh_512 = NULL; 11189837Skris DH *dh_1024 = NULL; 11289837Skris FILE *paramfile; 11389837Skris 11489837Skris ... 11589837Skris /* "openssl dhparam -out dh_param_512.pem -2 512" */ 11689837Skris paramfile = fopen("dh_param_512.pem", "r"); 11789837Skris if (paramfile) { 11889837Skris dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 11989837Skris fclose(paramfile); 12089837Skris } 12189837Skris /* "openssl dhparam -out dh_param_1024.pem -2 1024" */ 12289837Skris paramfile = fopen("dh_param_1024.pem", "r"); 12389837Skris if (paramfile) { 12489837Skris dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 12589837Skris fclose(paramfile); 12689837Skris } 12789837Skris ... 12889837Skris 12989837Skris /* "openssl dhparam -C -2 512" etc... */ 13089837Skris DH *get_dh512() { ... } 13189837Skris DH *get_dh1024() { ... } 13289837Skris 13389837Skris DH *tmp_dh_callback(SSL *s, int is_export, int keylength) 13489837Skris { 13589837Skris DH *dh_tmp=NULL; 13689837Skris 13789837Skris switch (keylength) { 13889837Skris case 512: 13989837Skris if (!dh_512) 14089837Skris dh_512 = get_dh512(); 14189837Skris dh_tmp = dh_512; 14289837Skris break; 14389837Skris case 1024: 14489837Skris if (!dh_1024) 14589837Skris dh_1024 = get_dh1024(); 14689837Skris dh_tmp = dh_1024; 14789837Skris break; 14889837Skris default: 14989837Skris /* Generating a key on the fly is very costly, so use what is there */ 15089837Skris setup_dh_parameters_like_above(); 15189837Skris } 15289837Skris return(dh_tmp); 15389837Skris } 15489837Skris 15589837Skris=head1 RETURN VALUES 15689837Skris 15789837SkrisSSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return 15889837Skrisdiagnostic output. 15989837Skris 16089837SkrisSSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 16189837Skrison failure. Check the error queue to find out the reason of failure. 16289837Skris 16389837Skris=head1 SEE ALSO 16489837Skris 16589837SkrisL<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 16689837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 16789837SkrisL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 16889837SkrisL<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> 16989837Skris 17089837Skris=cut 171