1=pod 2 3=head1 NAME 4 5SSL_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 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx, 12 DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 13 long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh); 14 15 void SSL_set_tmp_dh_callback(SSL *ctx, 16 DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); 17 long SSL_set_tmp_dh(SSL *ssl, DH *dh) 18 19=head1 DESCRIPTION 20 21SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be 22used when a DH parameters are required to B<tmp_dh_callback>. 23The callback is inherited by all B<ssl> objects created from B<ctx>. 24 25SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. 26The key is inherited by all B<ssl> objects created from B<ctx>. 27 28SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. 29 30SSL_set_tmp_dh() sets the parameters only for B<ssl>. 31 32These functions apply to SSL/TLS servers only. 33 34=head1 NOTES 35 36When using a cipher with RSA authentication, an ephemeral DH key exchange 37can take place. Ciphers with DSA keys always use ephemeral DH keys as well. 38In these cases, the session data are negotiated using the 39ephemeral/temporary DH key and the key supplied and certified 40by the certificate chain is only used for signing. 41Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. 42 43Using ephemeral DH key exchange yields forward secrecy, as the connection 44can only be decrypted, when the DH key is known. By generating a temporary 45DH key inside the server application that is lost when the application 46is left, it becomes impossible for an attacker to decrypt past sessions, 47even if he gets hold of the normal (certified) key, as this key was 48only used for signing. 49 50In order to perform a DH key exchange the server must use a DH group 51(DH parameters) and generate a DH key. 52The server will always generate a new DH key during the negotiation 53if either the DH parameters are supplied via callback or the 54SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both). 55It will immediately create a DH key if DH parameters are supplied via 56SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. 57In this case, 58it may happen that a key is generated on initialization without later 59being needed, while on the other hand the computer time during the 60negotiation is being saved. 61 62If "strong" primes were used to generate the DH parameters, it is not strictly 63necessary to generate a new key for each handshake but it does improve forward 64secrecy. If it is not assured, that "strong" primes were used (see especially 65the section about DSA parameters below), SSL_OP_SINGLE_DH_USE must be used 66in order to prevent small subgroup attacks. Always using SSL_OP_SINGLE_DH_USE 67has an impact on the computer time needed during negotiation, but it is not 68very large, so application authors/users should consider to always enable 69this option. 70 71As generating DH parameters is extremely time consuming, an application 72should not generate the parameters on the fly but supply the parameters. 73DH parameters can be reused, as the actual key is newly generated during 74the negotiation. The risk in reusing DH parameters is that an attacker 75may specialize on a very often used DH group. Applications should therefore 76generate their own DH parameters during the installation process using the 77openssl L<dhparam(1)|dhparam(1)> application. In order to reduce the computer 78time needed for this generation, it is possible to use DSA parameters 79instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE 80is mandatory. 81 82Application authors may compile in DH parameters. Files dh512.pem, 83dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current 84version of the OpenSSL distribution contain the 'SKIP' DH parameters, 85which use safe primes and were generated verifiably pseudo-randomly. 86These files can be converted into C code using the B<-C> option of the 87L<dhparam(1)|dhparam(1)> application. 88Authors may also generate their own set of parameters using 89L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were 90generated. The generation of DH parameters during installation is therefore 91recommended. 92 93An application may either directly specify the DH parameters or 94can supply the DH parameters via a callback function. The callback approach 95has the advantage, that the callback may supply DH parameters for different 96key lengths. 97 98The B<tmp_dh_callback> is called with the B<keylength> needed and 99the B<is_export> information. The B<is_export> flag is set, when the 100ephemeral DH key exchange is performed with an export cipher. 101 102=head1 EXAMPLES 103 104Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling 105partly left out.) 106 107 ... 108 /* Set up ephemeral DH stuff */ 109 DH *dh_512 = NULL; 110 DH *dh_1024 = NULL; 111 FILE *paramfile; 112 113 ... 114 /* "openssl dhparam -out dh_param_512.pem -2 512" */ 115 paramfile = fopen("dh_param_512.pem", "r"); 116 if (paramfile) { 117 dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 118 fclose(paramfile); 119 } 120 /* "openssl dhparam -out dh_param_1024.pem -2 1024" */ 121 paramfile = fopen("dh_param_1024.pem", "r"); 122 if (paramfile) { 123 dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); 124 fclose(paramfile); 125 } 126 ... 127 128 /* "openssl dhparam -C -2 512" etc... */ 129 DH *get_dh512() { ... } 130 DH *get_dh1024() { ... } 131 132 DH *tmp_dh_callback(SSL *s, int is_export, int keylength) 133 { 134 DH *dh_tmp=NULL; 135 136 switch (keylength) { 137 case 512: 138 if (!dh_512) 139 dh_512 = get_dh512(); 140 dh_tmp = dh_512; 141 break; 142 case 1024: 143 if (!dh_1024) 144 dh_1024 = get_dh1024(); 145 dh_tmp = dh_1024; 146 break; 147 default: 148 /* Generating a key on the fly is very costly, so use what is there */ 149 setup_dh_parameters_like_above(); 150 } 151 return(dh_tmp); 152 } 153 154=head1 RETURN VALUES 155 156SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return 157diagnostic output. 158 159SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 160on failure. Check the error queue to find out the reason of failure. 161 162=head1 SEE ALSO 163 164L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>, 165L<SSL_CTX_set_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>, 166L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>, 167L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)> 168 169=cut 170