]>
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 | |
ffaef3f1 DSH |
51 | (DH parameters) and generate a DH key. The server will always generate |
52 | a new DH key during the negotiation. | |
4db48ec0 LJ |
53 | |
54 | As generating DH parameters is extremely time consuming, an application | |
55 | should not generate the parameters on the fly but supply the parameters. | |
56 | DH parameters can be reused, as the actual key is newly generated during | |
57 | the negotiation. The risk in reusing DH parameters is that an attacker | |
37f599bc | 58 | may specialize on a very often used DH group. Applications should therefore |
3b80e3aa | 59 | generate their own DH parameters during the installation process using the |
9b86974e | 60 | openssl L<dhparam(1)> application. This application |
1f302db3 | 61 | guarantees that "strong" primes are used. |
37f599bc | 62 | |
1f302db3 | 63 | Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current |
37f599bc LJ |
64 | version of the OpenSSL distribution contain the 'SKIP' DH parameters, |
65 | which use safe primes and were generated verifiably pseudo-randomly. | |
66 | These files can be converted into C code using the B<-C> option of the | |
9b86974e | 67 | L<dhparam(1)> application. Generation of custom DH |
1f302db3 | 68 | parameters during installation should still be preferred to stop an |
1554d553 EK |
69 | attacker from specializing on a commonly used group. File dh1024.pem |
70 | contains old parameters that must not be used by applications. | |
37f599bc LJ |
71 | |
72 | An application may either directly specify the DH parameters or | |
1f302db3 | 73 | can supply the DH parameters via a callback function. |
4db48ec0 | 74 | |
1f302db3 EK |
75 | Previous versions of the callback used B<is_export> and B<keylength> |
76 | parameters to control parameter generation for export and non-export | |
77 | cipher suites. Modern servers that do not support export ciphersuites | |
ffaef3f1 DSH |
78 | are advised to either use SSL_CTX_set_tmp_dh() or alternatively, use |
79 | the callback but ignore B<keylength> and B<is_export> and simply | |
80 | supply at least 2048-bit parameters in the callback. | |
4db48ec0 LJ |
81 | |
82 | =head1 EXAMPLES | |
83 | ||
1f302db3 | 84 | Setup DH parameters with a key length of 2048 bits. (Error handling |
4db48ec0 LJ |
85 | partly left out.) |
86 | ||
1f302db3 EK |
87 | Command-line parameter generation: |
88 | $ openssl dhparam -out dh_param_2048.pem 2048 | |
89 | ||
90 | Code for setting up parameters during server initialization: | |
4db48ec0 LJ |
91 | |
92 | ... | |
1f302db3 EK |
93 | SSL_CTX ctx = SSL_CTX_new(); |
94 | ... | |
95 | ||
96 | /* Set up ephemeral DH parameters. */ | |
97 | DH *dh_2048 = NULL; | |
98 | FILE *paramfile; | |
99 | paramfile = fopen("dh_param_2048.pem", "r"); | |
4db48ec0 | 100 | if (paramfile) { |
1f302db3 | 101 | dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL); |
4db48ec0 | 102 | fclose(paramfile); |
1f302db3 EK |
103 | } else { |
104 | /* Error. */ | |
4db48ec0 | 105 | } |
1f302db3 EK |
106 | if (dh_2048 == NULL) { |
107 | /* Error. */ | |
4db48ec0 | 108 | } |
1f302db3 EK |
109 | if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) { |
110 | /* Error. */ | |
4db48ec0 | 111 | } |
1f302db3 | 112 | ... |
4db48ec0 LJ |
113 | |
114 | =head1 RETURN VALUES | |
115 | ||
116 | SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return | |
117 | diagnostic output. | |
118 | ||
119 | SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0 | |
120 | on failure. Check the error queue to find out the reason of failure. | |
121 | ||
122 | =head1 SEE ALSO | |
123 | ||
9b86974e RS |
124 | L<ssl(3)>, L<SSL_CTX_set_cipher_list(3)>, |
125 | L<SSL_CTX_set_tmp_rsa_callback(3)>, | |
126 | L<SSL_CTX_set_options(3)>, | |
127 | L<ciphers(1)>, L<dhparam(1)> | |
4db48ec0 LJ |
128 | |
129 | =cut | |
e2f92610 RS |
130 | |
131 | =head1 COPYRIGHT | |
132 | ||
133 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
134 | ||
135 | Licensed under the OpenSSL license (the "License"). You may not use | |
136 | this file except in compliance with the License. You can obtain a copy | |
137 | in the file LICENSE in the source distribution or at | |
138 | L<https://www.openssl.org/source/license.html>. | |
139 | ||
140 | =cut |