doc/ssl/SSL_CTX_set_tmp_dh_callback.pod

   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 paramters 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 as anonymous ciphers. In this case 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
  44 Using ephemeral DH key exchange yields forward secrecy, as the connection
  45 can only be decrypted, when the DH key is known. By generating a temporary
  46 DH key inside the server application that is lost when the application
  47 is left, it becomes impossible for an attacker to decrypt past sessions,
  48 even if he gets hold of the normal (certified) key, as this key was
  49 only used for signing.
  50
  51 In order to perform a DH key exchange the server must use a DH group
  52 (DH parameters) and generate a DH key. The server will automatically
  53 generate the DH key when required, as it is computationally cheap
  54 (retrieve a random number). The server will reuse the DH key for further
  55 connections, unless the SSL_OP_SINGLE_DH_USE option of
  56 L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set, in which case
  57 a new DH key for each negotiation will be generated.
  58
  59 As generating DH parameters is extremely time consuming, an application
  60 should not generate the parameters on the fly but supply the parameters.
  61 DH parameters can be reused, as the actual key is newly generated during
  62 the negotiation. The risk in reusing DH parameters is that an attacker
  63 may specialize on a very often used DH group. Therefore application authors
  64 should not copy the DH parameters from other applications or the OpenSSL
  65 example application, if they compile in parameters, but generate their
  66 own set of parameters using e.g. the openssl L<dhparam(1)|dhparam(1)>
  67 application with the B<-C> option. An application may also generate
  68 its own set of DH parameters during the installation procedure on a specific
  69 host, so that each host uses different parameters.
  70
  71 An application my either directly specify the DH parameters or
  72 can supply the DH parameters via a callback function. The callback approach
  73 has the advantage, that the callback may supply DH parameters for different
  74 key lengths.
  75
  76 The B<tmp_dh_callback> is called with the B<keylength> needed and
  77 the B<is_export> information. The B<is_export> flag is set, when the
  78 ephemeral DH key exchange is performed with an export cipher.
  79
  80 =head1 EXAMPLES
  81
  82 Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
  83 partly left out.)
  84
  85  ...
  86  /* Set up ephemeral DH stuff */
  87  DH *dh_512 = NULL;
  88  DH *dh_1024 = NULL;
  89  FILE *paramfile;
  90
  91  ...
  92  /* "openssl dhparam -out dh_param_512.pem -2 512" */
  93  paramfile = fopen("dh_param_512.pem", "r");
  94  if (paramfile) {
  95    dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
  96    fclose(paramfile);
  97  }
  98  /* "openssl dhparam -out dh_param_1024.pem -2 1024" */
  99  paramfile = fopen("dh_param_1024.pem", "r");
 100  if (paramfile) {
 101    dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
 102    fclose(paramfile);
 103  }
 104  ...
 105
 106  /* "openssl dhparam -C -2 512" etc... */
 107  DH *get_dh512() { ... }
 108  DH *get_dh1024() { ... }
 109
 110  DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
 111  {
 112     DH *dh_tmp=NULL;
 113
 114     switch (keylength) {
 115     case 512:
 116       if (!dh_512)
 117         dh_512 = get_dh512();
 118       dh_tmp = dh_512;
 119       break;
 120     case 1024:
 121       if (!dh_1024)
 122         dh_1024 = get_dh1024();
 123       dh_tmp = dh_1024;
 124       break;
 125     default:
 126       /* Generating a key on the fly is very costly, so use what is there */
 127       setup_dh_parameters_like_above();
 128     }
 129     return(dh_tmp);
 130  }
 131
 132 =head1 RETURN VALUES
 133
 134 SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
 135 diagnostic output.
 136
 137 SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
 138 on failure. Check the error queue to find out the reason of failure.
 139
 140 =head1 SEE ALSO
 141
 142 L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
 143 L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
 144 L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
 145
 146 =cut