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 15269686Sjkim void SSL_set_tmp_dh_callback(SSL *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=head1 DESCRIPTION 2089837Skris 2189837SkrisSSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be 2289837Skrisused when a DH parameters are required to B<tmp_dh_callback>. 2389837SkrisThe callback is inherited by all B<ssl> objects created from B<ctx>. 2489837Skris 2589837SkrisSSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. 2689837SkrisThe key is inherited by all B<ssl> objects created from B<ctx>. 2789837Skris 2889837SkrisSSL_set_tmp_dh_callback() sets the callback only for B<ssl>. 2989837Skris 3089837SkrisSSL_set_tmp_dh() sets the parameters only for B<ssl>. 3189837Skris 3289837SkrisThese functions apply to SSL/TLS servers only. 3389837Skris 3489837Skris=head1 NOTES 3589837Skris 3689837SkrisWhen using a cipher with RSA authentication, an ephemeral DH key exchange 3789837Skriscan take place. Ciphers with DSA keys always use ephemeral DH keys as well. 3889837SkrisIn these cases, the session data are negotiated using the 3989837Skrisephemeral/temporary DH key and the key supplied and certified 4089837Skrisby the certificate chain is only used for signing. 4189837SkrisAnonymous ciphers (without a permanent server key) also use ephemeral DH keys. 4289837Skris 4389837SkrisUsing ephemeral DH key exchange yields forward secrecy, as the connection 4489837Skriscan only be decrypted, when the DH key is known. By generating a temporary 4589837SkrisDH key inside the server application that is lost when the application 4689837Skrisis left, it becomes impossible for an attacker to decrypt past sessions, 4789837Skriseven if he gets hold of the normal (certified) key, as this key was 4889837Skrisonly used for signing. 4989837Skris 5089837SkrisIn order to perform a DH key exchange the server must use a DH group 51295016Sjkim(DH parameters) and generate a DH key. The server will always generate 52295016Sjkima new DH key during the negotiation. 5389837Skris 5489837SkrisAs generating DH parameters is extremely time consuming, an application 5589837Skrisshould not generate the parameters on the fly but supply the parameters. 5689837SkrisDH parameters can be reused, as the actual key is newly generated during 5789837Skristhe negotiation. The risk in reusing DH parameters is that an attacker 5889837Skrismay specialize on a very often used DH group. Applications should therefore 5989837Skrisgenerate their own DH parameters during the installation process using the 60284285Sjkimopenssl L<dhparam(1)|dhparam(1)> application. This application 61284285Sjkimguarantees that "strong" primes are used. 6289837Skris 63284285SjkimFiles dh2048.pem, and dh4096.pem in the 'apps' directory of the current 6489837Skrisversion of the OpenSSL distribution contain the 'SKIP' DH parameters, 6589837Skriswhich use safe primes and were generated verifiably pseudo-randomly. 6689837SkrisThese files can be converted into C code using the B<-C> option of the 67284285SjkimL<dhparam(1)|dhparam(1)> application. Generation of custom DH 68284285Sjkimparameters during installation should still be preferred to stop an 69284285Sjkimattacker from specializing on a commonly used group. Files dh1024.pem 70284285Sjkimand dh512.pem contain old parameters that must not be used by 71284285Sjkimapplications. 7289837Skris 7389837SkrisAn application may either directly specify the DH parameters or 74284285Sjkimcan supply the DH parameters via a callback function. 7589837Skris 76284285SjkimPrevious versions of the callback used B<is_export> and B<keylength> 77284285Sjkimparameters to control parameter generation for export and non-export 78284285Sjkimcipher suites. Modern servers that do not support export ciphersuites 79295016Sjkimare advised to either use SSL_CTX_set_tmp_dh() or alternatively, use 80295016Sjkimthe callback but ignore B<keylength> and B<is_export> and simply 81295016Sjkimsupply at least 2048-bit parameters in the callback. 8289837Skris 8389837Skris=head1 EXAMPLES 8489837Skris 85284285SjkimSetup DH parameters with a key length of 2048 bits. (Error handling 8689837Skrispartly left out.) 8789837Skris 88284285Sjkim Command-line parameter generation: 89284285Sjkim $ openssl dhparam -out dh_param_2048.pem 2048 90284285Sjkim 91284285Sjkim Code for setting up parameters during server initialization: 92284285Sjkim 9389837Skris ... 94284285Sjkim SSL_CTX ctx = SSL_CTX_new(); 95284285Sjkim ... 96284285Sjkim 97284285Sjkim /* Set up ephemeral DH parameters. */ 98284285Sjkim DH *dh_2048 = NULL; 9989837Skris FILE *paramfile; 100284285Sjkim paramfile = fopen("dh_param_2048.pem", "r"); 10189837Skris if (paramfile) { 102284285Sjkim dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 10389837Skris fclose(paramfile); 104284285Sjkim } else { 105284285Sjkim /* Error. */ 10689837Skris } 107284285Sjkim if (dh_2048 == NULL) { 108284285Sjkim /* Error. */ 10989837Skris } 110284285Sjkim if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { 111284285Sjkim /* Error. */ 112284285Sjkim } 11389837Skris ... 11489837Skris 11589837Skris=head1 RETURN VALUES 11689837Skris 11789837SkrisSSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return 11889837Skrisdiagnostic output. 11989837Skris 12089837SkrisSSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 12189837Skrison failure. Check the error queue to find out the reason of failure. 12289837Skris 12389837Skris=head1 SEE ALSO 12489837Skris 12589837SkrisL<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 12689837SkrisL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 12789837SkrisL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 12889837SkrisL<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> 12989837Skris 13089837Skris=cut 131