SSL_CTX_set_tmp_dh_callback.pod revision 269686
1234370Sjasone=pod 2234370Sjasone 3234370Sjasone=head1 NAME 4234370Sjasone 5234370SjasoneSSL_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 6234370Sjasone 7234543Sjasone=head1 SYNOPSIS 8234370Sjasone 9234370Sjasone #include <openssl/ssl.h> 10234370Sjasone 11234370Sjasone void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, 12234370Sjasone DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 13234370Sjasone long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); 14234370Sjasone 15234370Sjasone void SSL_set_tmp_dh_callback(SSL *ctx, 16234370Sjasone DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 17234370Sjasone long SSL_set_tmp_dh(SSL *ssl, DH *dh) 18234370Sjasone 19234370Sjasone=head1 DESCRIPTION 20234370Sjasone 21234370SjasoneSSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be 22234370Sjasoneused when a DH parameters are required to B<tmp_dh_callback>. 23234370SjasoneThe callback is inherited by all B<ssl> objects created from B<ctx>. 24234370Sjasone 25234370SjasoneSSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. 26234370SjasoneThe key is inherited by all B<ssl> objects created from B<ctx>. 27234370Sjasone 28234370SjasoneSSL_set_tmp_dh_callback() sets the callback only for B<ssl>. 29234370Sjasone 30234370SjasoneSSL_set_tmp_dh() sets the parameters only for B<ssl>. 31234370Sjasone 32234370SjasoneThese functions apply to SSL/TLS servers only. 33234370Sjasone 34234370Sjasone=head1 NOTES 35234370Sjasone 36234370SjasoneWhen using a cipher with RSA authentication, an ephemeral DH key exchange 37234370Sjasonecan take place. Ciphers with DSA keys always use ephemeral DH keys as well. 38234370SjasoneIn these cases, the session data are negotiated using the 39234370Sjasoneephemeral/temporary DH key and the key supplied and certified 40234370Sjasoneby the certificate chain is only used for signing. 41234370SjasoneAnonymous ciphers (without a permanent server key) also use ephemeral DH keys. 42234370Sjasone 43234370SjasoneUsing ephemeral DH key exchange yields forward secrecy, as the connection 44234370Sjasonecan only be decrypted, when the DH key is known. By generating a temporary 45234370SjasoneDH key inside the server application that is lost when the application 46234370Sjasoneis left, it becomes impossible for an attacker to decrypt past sessions, 47234370Sjasoneeven if he gets hold of the normal (certified) key, as this key was 48234370Sjasoneonly used for signing. 49234370Sjasone 50234370SjasoneIn order to perform a DH key exchange the server must use a DH group 51234370Sjasone(DH parameters) and generate a DH key. The server will always generate a new 52234370SjasoneDH key during the negotiation, when the DH parameters are supplied via 53234370Sjasonecallback and/or when the SSL_OP_SINGLE_DH_USE option of 54234370SjasoneL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set. It will 55234370Sjasoneimmediately create a DH key, when DH parameters are supplied via 56234370SjasoneSSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. In this case, 57234370Sjasoneit may happen that a key is generated on initialization without later 58234370Sjasonebeing needed, while on the other hand the computer time during the 59234370Sjasonenegotiation is being saved. 60234370Sjasone 61234370SjasoneIf "strong" primes were used to generate the DH parameters, it is not strictly 62234370Sjasonenecessary to generate a new key for each handshake but it does improve forward 63234370Sjasonesecrecy. If it is not assured, that "strong" primes were used (see especially 64234370Sjasonethe section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used 65234370Sjasonein order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE 66234370Sjasonehas an impact on the computer time needed during negotiation, but it is not 67234370Sjasonevery large, so application authors/users should consider to always enable 68234370Sjasonethis option. 69234370Sjasone 70234370SjasoneAs generating DH parameters is extremely time consuming, an application 71234370Sjasoneshould not generate the parameters on the fly but supply the parameters. 72234370SjasoneDH parameters can be reused, as the actual key is newly generated during 73234370Sjasonethe negotiation. The risk in reusing DH parameters is that an attacker 74234370Sjasonemay specialize on a very often used DH group. Applications should therefore 75234370Sjasonegenerate their own DH parameters during the installation process using the 76234370Sjasoneopenssl L<dhparam(1)|dhparam(1)> application. In order to reduce the computer 77234370Sjasonetime needed for this generation, it is possible to use DSA parameters 78234370Sjasoneinstead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE 79234370Sjasoneis mandatory. 80234370Sjasone 81234370SjasoneApplication authors may compile in DH parameters. Files dh512.pem, 82234370Sjasonedh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current 83234370Sjasoneversion of the OpenSSL distribution contain the 'SKIP' DH parameters, 84234370Sjasonewhich use safe primes and were generated verifiably pseudo-randomly. 85234370SjasoneThese files can be converted into C code using the B<-C> option of the 86234370SjasoneL<dhparam(1)|dhparam(1)> application. 87234370SjasoneAuthors may also generate their own set of parameters using 88234370SjasoneL<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were 89234370Sjasonegenerated. The generation of DH parameters during installation is therefore 90234370Sjasonerecommended. 91234370Sjasone 92234370SjasoneAn application may either directly specify the DH parameters or 93234370Sjasonecan supply the DH parameters via a callback function. The callback approach 94234370Sjasonehas the advantage, that the callback may supply DH parameters for different 95234370Sjasonekey lengths. 96234370Sjasone 97234370SjasoneThe B<tmp_dh_callback> is called with the B<keylength> needed and 98234370Sjasonethe B<is_export> information. The B<is_export> flag is set, when the 99234370Sjasoneephemeral DH key exchange is performed with an export cipher. 100234370Sjasone 101234370Sjasone=head1 EXAMPLES 102234370Sjasone 103234370SjasoneHandle DH parameters for key lengths of 512 and 1024 bits. (Error handling 104234370Sjasonepartly left out.) 105234370Sjasone 106234370Sjasone ... 107234370Sjasone /* Set up ephemeral DH stuff */ 108234370Sjasone DH *dh_512 = NULL; 109234543Sjasone DH *dh_1024 = NULL; 110234370Sjasone FILE *paramfile; 111234370Sjasone 112234370Sjasone ... 113234370Sjasone /* "openssl dhparam -out dh_param_512.pem -2 512" */ 114234569Sjasone paramfile = fopen("dh_param_512.pem", "r"); 115234370Sjasone if (paramfile) { 116234370Sjasone dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 117234370Sjasone fclose(paramfile); 118234370Sjasone } 119234370Sjasone /* "openssl dhparam -out dh_param_1024.pem -2 1024" */ 120234370Sjasone paramfile = fopen("dh_param_1024.pem", "r"); 121234370Sjasone if (paramfile) { 122234370Sjasone dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 123234370Sjasone fclose(paramfile); 124234543Sjasone } 125234370Sjasone ... 126234370Sjasone 127234370Sjasone /* "openssl dhparam -C -2 512" etc... */ 128234370Sjasone DH *get_dh512() { ... } 129234370Sjasone DH *get_dh1024() { ... } 130234370Sjasone 131234370Sjasone DH *tmp_dh_callback(SSL *s, int is_export, int keylength) 132234370Sjasone { 133234370Sjasone DH *dh_tmp=NULL; 134234370Sjasone 135234370Sjasone switch (keylength) { 136234370Sjasone case 512: 137234370Sjasone if (!dh_512) 138234370Sjasone dh_512 = get_dh512(); 139234370Sjasone dh_tmp = dh_512; 140234370Sjasone break; 141234370Sjasone case 1024: 142234370Sjasone if (!dh_1024) 143234370Sjasone dh_1024 = get_dh1024(); 144234370Sjasone dh_tmp = dh_1024; 145234370Sjasone break; 146234370Sjasone default: 147234370Sjasone /* Generating a key on the fly is very costly, so use what is there */ 148234370Sjasone setup_dh_parameters_like_above(); 149234370Sjasone } 150234370Sjasone return(dh_tmp); 151234370Sjasone } 152234370Sjasone 153234370Sjasone=head1 RETURN VALUES 154234370Sjasone 155234370SjasoneSSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return 156234370Sjasonediagnostic output. 157234370Sjasone 158234370SjasoneSSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 159234370Sjasoneon failure. Check the error queue to find out the reason of failure. 160234370Sjasone 161234370Sjasone=head1 SEE ALSO 162234370Sjasone 163234370SjasoneL<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 164234370SjasoneL<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 165234370SjasoneL<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 166234370SjasoneL<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> 167234370Sjasone 168234370Sjasone=cut 169234370Sjasone