SSL_CTX_set_tmp_dh_callback.pod revision 295016
1213365Smarcel=pod 2214006Smarcel 3213365Smarcel=head1 NAME 4213365Smarcel 5213365SmarcelSSL_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 6213365Smarcel 7213365Smarcel=head1 SYNOPSIS 8213365Smarcel 9213365Smarcel #include <openssl/ssl.h> 10213365Smarcel 11213365Smarcel void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, 12213365Smarcel DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 13213365Smarcel long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); 14213365Smarcel 15213365Smarcel void SSL_set_tmp_dh_callback(SSL *ctx, 16213365Smarcel DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 17213365Smarcel long SSL_set_tmp_dh(SSL *ssl, DH *dh) 18213365Smarcel 19213365Smarcel=head1 DESCRIPTION 20213365Smarcel 21213365SmarcelSSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be 22213365Smarcelused when a DH parameters are required to B<tmp_dh_callback>. 23213365SmarcelThe callback is inherited by all B<ssl> objects created from B<ctx>. 24213365Smarcel 25213365SmarcelSSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. 26213365SmarcelThe key is inherited by all B<ssl> objects created from B<ctx>. 27213365Smarcel 28213365SmarcelSSL_set_tmp_dh_callback() sets the callback only for B<ssl>. 29213365Smarcel 30213365SmarcelSSL_set_tmp_dh() sets the parameters only for B<ssl>. 31213365Smarcel 32213365SmarcelThese functions apply to SSL/TLS servers only. 33213365Smarcel 34213365Smarcel=head1 NOTES 35213365Smarcel 36213365SmarcelWhen using a cipher with RSA authentication, an ephemeral DH key exchange 37213365Smarcelcan take place. Ciphers with DSA keys always use ephemeral DH keys as well. 38214006SmarcelIn these cases, the session data are negotiated using the 39214006Smarcelephemeral/temporary DH key and the key supplied and certified 40213365Smarcelby the certificate chain is only used for signing. 41213365SmarcelAnonymous ciphers (without a permanent server key) also use ephemeral DH keys. 42213365Smarcel 43213365SmarcelUsing ephemeral DH key exchange yields forward secrecy, as the connection 44213365Smarcelcan only be decrypted, when the DH key is known. By generating a temporary 45228634SavgDH key inside the server application that is lost when the application 46213365Smarcelis left, it becomes impossible for an attacker to decrypt past sessions, 47213365Smarceleven if he gets hold of the normal (certified) key, as this key was 48213365Smarcelonly used for signing. 49213365Smarcel 50214006SmarcelIn order to perform a DH key exchange the server must use a DH group 51213365Smarcel(DH parameters) and generate a DH key. The server will always generate 52213365Smarcela new DH key during the negotiation. 53213365Smarcel 54213365SmarcelAs generating DH parameters is extremely time consuming, an application 55213365Smarcelshould not generate the parameters on the fly but supply the parameters. 56213365SmarcelDH parameters can be reused, as the actual key is newly generated during 57213365Smarcelthe negotiation. The risk in reusing DH parameters is that an attacker 58223919Saemay specialize on a very often used DH group. Applications should therefore 59214006Smarcelgenerate their own DH parameters during the installation process using the 60213365Smarcelopenssl L<dhparam(1)|dhparam(1)> application. This application 61213365Smarcelguarantees that "strong" primes are used. 62213365Smarcel 63213365SmarcelFiles dh2048.pem, and dh4096.pem in the 'apps' directory of the current 64213365Smarcelversion of the OpenSSL distribution contain the 'SKIP' DH parameters, 65213365Smarcelwhich use safe primes and were generated verifiably pseudo-randomly. 66213365SmarcelThese files can be converted into C code using the B<-C> option of the 67213365SmarcelL<dhparam(1)|dhparam(1)> application. Generation of custom DH 68213365Smarcelparameters during installation should still be preferred to stop an 69213365Smarcelattacker from specializing on a commonly used group. Files dh1024.pem 70213365Smarceland dh512.pem contain old parameters that must not be used by 71213365Smarcelapplications. 72213365Smarcel 73213365SmarcelAn application may either directly specify the DH parameters or 74213365Smarcelcan supply the DH parameters via a callback function. 75213365Smarcel 76213365SmarcelPrevious versions of the callback used B<is_export> and B<keylength> 77213365Smarcelparameters to control parameter generation for export and non-export 78213365Smarcelcipher suites. Modern servers that do not support export ciphersuites 79213365Smarcelare advised to either use SSL_CTX_set_tmp_dh() or alternatively, use 80213365Smarcelthe callback but ignore B<keylength> and B<is_export> and simply 81213365Smarcelsupply at least 2048-bit parameters in the callback. 82213365Smarcel 83213365Smarcel=head1 EXAMPLES 84213365Smarcel 85213365SmarcelSetup DH parameters with a key length of 2048 bits. (Error handling 86213365Smarcelpartly left out.) 87213365Smarcel 88213365Smarcel Command-line parameter generation: 89214006Smarcel $ openssl dhparam -out dh_param_2048.pem 2048 90214006Smarcel 91214006Smarcel Code for setting up parameters during server initialization: 92213365Smarcel 93214006Smarcel ... 94214006Smarcel SSL_CTX ctx = SSL_CTX_new(); 95213365Smarcel ... 96214006Smarcel 97213365Smarcel /* Set up ephemeral DH parameters. */ 98287107Strasz DH *dh_2048 = NULL; 99287107Strasz FILE *paramfile; 100287107Strasz paramfile = fopen("dh_param_2048.pem", "r"); 101287107Strasz if (paramfile) { 102287107Strasz dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 103214006Smarcel fclose(paramfile); 104213365Smarcel } else { 105267351Smav /* Error. */ 106267351Smav } 107267351Smav if (dh_2048 == NULL) { 108213365Smarcel /* Error. */ 109213365Smarcel } 110213365Smarcel if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { 111213365Smarcel /* Error. */ 112213365Smarcel } 113213365Smarcel ... 114213365Smarcel 115213365Smarcel=head1 RETURN VALUES 116214006Smarcel 117214006SmarcelSSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return 118214006Smarceldiagnostic output. 119214006Smarcel 120214006SmarcelSSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 121214006Smarcelon failure. Check the error queue to find out the reason of failure. 122214006Smarcel 123214006Smarcel=head1 SEE ALSO 124214006Smarcel 125214006SmarcelL<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 126213365SmarcelL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 127213365SmarcelL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 128214006SmarcelL<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> 129214006Smarcel 130253910Smarcel=cut 131214006Smarcel