SSL_CTX_set_tmp_dh_callback.pod revision 279264 
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