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