]>
Commit | Line | Data |
---|---|---|
4db48ec0 LJ |
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 | ||
fc1d88f0 | 15 | void SSL_set_tmp_dh_callback(SSL *ctx, |
4db48ec0 LJ |
16 | DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength)); |
17 | long SSL_set_tmp_dh(SSL *ssl, DH *dh) | |
18 | ||
4db48ec0 LJ |
19 | =head1 DESCRIPTION |
20 | ||
21 | SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be | |
22 | used when a DH parameters are required to B<tmp_dh_callback>. | |
23 | The callback is inherited by all B<ssl> objects created from B<ctx>. | |
24 | ||
25 | SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>. | |
26 | The key is inherited by all B<ssl> objects created from B<ctx>. | |
27 | ||
28 | SSL_set_tmp_dh_callback() sets the callback only for B<ssl>. | |
29 | ||
3b80e3aa | 30 | SSL_set_tmp_dh() sets the parameters only for B<ssl>. |
4db48ec0 LJ |
31 | |
32 | These functions apply to SSL/TLS servers only. | |
33 | ||
34 | =head1 NOTES | |
35 | ||
36 | When using a cipher with RSA authentication, an ephemeral DH key exchange | |
37f599bc LJ |
37 | can take place. Ciphers with DSA keys always use ephemeral DH keys as well. |
38 | In these cases, the session data are negotiated using the | |
4db48ec0 LJ |
39 | ephemeral/temporary DH key and the key supplied and certified |
40 | by the certificate chain is only used for signing. | |
37f599bc | 41 | Anonymous ciphers (without a permanent server key) also use ephemeral DH keys. |
4db48ec0 LJ |
42 | |
43 | Using ephemeral DH key exchange yields forward secrecy, as the connection | |
44 | can only be decrypted, when the DH key is known. By generating a temporary | |
45 | DH key inside the server application that is lost when the application | |
46 | is left, it becomes impossible for an attacker to decrypt past sessions, | |
47 | even if he gets hold of the normal (certified) key, as this key was | |
48 | only used for signing. | |
49 | ||
50 | In order to perform a DH key exchange the server must use a DH group | |
fa60b909 DG |
51 | (DH parameters) and generate a DH key. |
52 | The server will always generate a new DH key during the negotiation | |
53 | if either the DH parameters are supplied via callback or the | |
54 | SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both). | |
55 | It will immediately create a DH key if DH parameters are supplied via | |
56 | SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set. | |
57 | In this case, | |
37f599bc LJ |
58 | it may happen that a key is generated on initialization without later |
59 | being needed, while on the other hand the computer time during the | |
60 | negotiation is being saved. | |
61 | ||
62 | If "strong" primes were used to generate the DH parameters, it is not strictly | |
63 | necessary to generate a new key for each handshake but it does improve forward | |
1f302db3 EK |
64 | secrecy. If it is not assured that "strong" primes were used, |
65 | SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup | |
66 | attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the | |
67 | computer time needed during negotiation, but it is not very large, so | |
68 | application authors/users should consider always enabling this option. | |
fa60b909 | 69 | The option is required to implement perfect forward secrecy (PFS). |
4db48ec0 LJ |
70 | |
71 | As generating DH parameters is extremely time consuming, an application | |
72 | should not generate the parameters on the fly but supply the parameters. | |
73 | DH parameters can be reused, as the actual key is newly generated during | |
74 | the negotiation. The risk in reusing DH parameters is that an attacker | |
37f599bc | 75 | may specialize on a very often used DH group. Applications should therefore |
3b80e3aa | 76 | generate their own DH parameters during the installation process using the |
9b86974e | 77 | openssl L<dhparam(1)> application. This application |
1f302db3 | 78 | guarantees that "strong" primes are used. |
37f599bc | 79 | |
1f302db3 | 80 | Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current |
37f599bc LJ |
81 | version of the OpenSSL distribution contain the 'SKIP' DH parameters, |
82 | which use safe primes and were generated verifiably pseudo-randomly. | |
83 | These files can be converted into C code using the B<-C> option of the | |
9b86974e | 84 | L<dhparam(1)> application. Generation of custom DH |
1f302db3 | 85 | parameters during installation should still be preferred to stop an |
1554d553 EK |
86 | attacker from specializing on a commonly used group. File dh1024.pem |
87 | contains old parameters that must not be used by applications. | |
37f599bc LJ |
88 | |
89 | An application may either directly specify the DH parameters or | |
1f302db3 | 90 | can supply the DH parameters via a callback function. |
4db48ec0 | 91 | |
1f302db3 EK |
92 | Previous versions of the callback used B<is_export> and B<keylength> |
93 | parameters to control parameter generation for export and non-export | |
94 | cipher suites. Modern servers that do not support export ciphersuites | |
95 | are advised to either use SSL_CTX_set_tmp_dh() in combination with | |
96 | SSL_OP_SINGLE_DH_USE, or alternatively, use the callback but ignore | |
97 | B<keylength> and B<is_export> and simply supply at least 2048-bit | |
98 | parameters in the callback. | |
4db48ec0 LJ |
99 | |
100 | =head1 EXAMPLES | |
101 | ||
1f302db3 | 102 | Setup DH parameters with a key length of 2048 bits. (Error handling |
4db48ec0 LJ |
103 | partly left out.) |
104 | ||
1f302db3 EK |
105 | Command-line parameter generation: |
106 | $ openssl dhparam -out dh_param_2048.pem 2048 | |
107 | ||
108 | Code for setting up parameters during server initialization: | |
4db48ec0 LJ |
109 | |
110 | ... | |
1f302db3 EK |
111 | SSL_CTX ctx = SSL_CTX_new(); |
112 | ... | |
113 | ||
114 | /* Set up ephemeral DH parameters. */ | |
115 | DH *dh_2048 = NULL; | |
116 | FILE *paramfile; | |
117 | paramfile = fopen("dh_param_2048.pem", "r"); | |
4db48ec0 | 118 | if (paramfile) { |
1f302db3 | 119 | dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); |
4db48ec0 | 120 | fclose(paramfile); |
1f302db3 EK |
121 | } else { |
122 | /* Error. */ | |
4db48ec0 | 123 | } |
1f302db3 EK |
124 | if (dh_2048 == NULL) { |
125 | /* Error. */ | |
4db48ec0 | 126 | } |
1f302db3 EK |
127 | if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { |
128 | /* Error. */ | |
4db48ec0 | 129 | } |
1f302db3 EK |
130 | SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE); |
131 | ... | |
4db48ec0 LJ |
132 | |
133 | =head1 RETURN VALUES | |
134 | ||
135 | SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return | |
136 | diagnostic output. | |
137 | ||
138 | SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 | |
139 | on failure. Check the error queue to find out the reason of failure. | |
140 | ||
141 | =head1 SEE ALSO | |
142 | ||
9b86974e RS |
143 | L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>, |
144 | L<SSL_CTX_set_tmp_rsa_callback(3)>, | |
145 | L<SSL_CTX_set_options(3)>, | |
146 | L<ciphers(1)>, L<dhparam(1)> | |
4db48ec0 LJ |
147 | |
148 | =cut |