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