SSL_CTX_set_tmp_dh_callback(3ssl)

1SSL_CTX_set_tmp_dh_callback(3)      OpenSSL     SSL_CTX_set_tmp_dh_callback(3)
2
3
4

NAME

6       SSL_CTX_set_tmp_dh_callback, SSL_CTX_set_tmp_dh,
7       SSL_set_tmp_dh_callback, SSL_set_tmp_dh - handle DH keys for ephemeral
8       key exchange
9

SYNOPSIS

11        #include <openssl/ssl.h>
12
13        void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
14                   DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
15        long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
16
17        void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
18                   DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
19        long SSL_set_tmp_dh(SSL *ssl, DH *dh)
20
21        DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
22

DESCRIPTION

24       SSL_CTX_set_tmp_dh_callback() sets the callback function for ctx to be
25       used when a DH parameters are required to tmp_dh_callback.  The
26       callback is inherited by all ssl objects created from ctx.
27
28       SSL_CTX_set_tmp_dh() sets DH parameters to be used to be dh.  The key
29       is inherited by all ssl objects created from ctx.
30
31       SSL_set_tmp_dh_callback() sets the callback only for ssl.
32
33       SSL_set_tmp_dh() sets the parameters only for ssl.
34
35       These functions apply to SSL/TLS servers only.
36

NOTES

38       When using a cipher with RSA authentication, an ephemeral DH key
39       exchange can take place. Ciphers with DSA keys always use ephemeral DH
40       keys as well.  In these cases, the session data are negotiated using
41       the ephemeral/temporary DH key and the key supplied and certified by
42       the certificate chain is only used for signing.  Anonymous ciphers
43       (without a permanent server key) also use ephemeral DH keys.
44
45       Using ephemeral DH key exchange yields forward secrecy, as the
46       connection can only be decrypted, when the DH key is known. By
47       generating a temporary DH key inside the server application that is
48       lost when the application is left, it becomes impossible for an
49       attacker to decrypt past sessions, even if he gets hold of the normal
50       (certified) key, as this key was only used for signing.
51
52       In order to perform a DH key exchange the server must use a DH group
53       (DH parameters) and generate a DH key. The server will always generate
54       a new DH key during the negotiation, when the DH parameters are
55       supplied via callback and/or when the SSL_OP_SINGLE_DH_USE option of
56       SSL_CTX_set_options(3) is set. It will immediately create a DH key,
57       when DH parameters are supplied via SSL_CTX_set_tmp_dh() and
58       SSL_OP_SINGLE_DH_USE is not set. In this case, it may happen that a key
59       is generated on initialization without later being needed, while on the
60       other hand the computer time during the negotiation is being saved.
61
62       If "strong" primes were used to generate the DH parameters, it is not
63       strictly necessary to generate a new key for each handshake but it does
64       improve forward secrecy. If it is not assured, that "strong" primes
65       were used (see especially the section about DSA parameters below),
66       SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup
67       attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the
68       computer time needed during negotiation, but it is not very large, so
69       application authors/users should consider to always enable this option.
70
71       As generating DH parameters is extremely time consuming, an application
72       should not generate the parameters on the fly but supply the
73       parameters.  DH parameters can be reused, as the actual key is newly
74       generated during the negotiation. The risk in reusing DH parameters is
75       that an attacker may specialize on a very often used DH group.
76       Applications should therefore generate their own DH parameters during
77       the installation process using the openssl dhparam(1) application. In
78       order to reduce the computer time needed for this generation, it is
79       possible to use DSA parameters instead (see dhparam(1)), but in this
80       case SSL_OP_SINGLE_DH_USE is mandatory.
81
82       Application authors may compile in DH parameters. Files dh512.pem,
83       dh1024.pem, dh2048.pem, and dh4096 in the 'apps' directory of current
84       version of the OpenSSL distribution contain the 'SKIP' DH parameters,
85       which use safe primes and were generated verifiably pseudo-randomly.
86       These files can be converted into C code using the -C option of the
87       dhparam(1) application.  Authors may also generate their own set of
88       parameters using dhparam(1), but a user may not be sure how the
89       parameters were generated. The generation of DH parameters during
90       installation is therefore recommended.
91
92       An application may either directly specify the DH parameters or can
93       supply the DH parameters via a callback function. The callback approach
94       has the advantage, that the callback may supply DH parameters for
95       different key lengths.
96
97       The tmp_dh_callback is called with the keylength needed and the
98       is_export information. The is_export flag is set, when the ephemeral DH
99       key exchange is performed with an export cipher.
100

EXAMPLES

102       Handle DH parameters for key lengths of 512 and 1024 bits. (Error
103       handling partly left out.)
104
105        ...
106        /* Set up ephemeral DH stuff */
107        DH *dh_512 = NULL;
108        DH *dh_1024 = NULL;
109        FILE *paramfile;
110
111        ...
112        /* "openssl dhparam -out dh_param_512.pem -2 512" */
113        paramfile = fopen("dh_param_512.pem", "r");
114        if (paramfile) {
115          dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
116          fclose(paramfile);
117        }
118        /* "openssl dhparam -out dh_param_1024.pem -2 1024" */
119        paramfile = fopen("dh_param_1024.pem", "r");
120        if (paramfile) {
121          dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
122          fclose(paramfile);
123        }
124        ...
125
126        /* "openssl dhparam -C -2 512" etc... */
127        DH *get_dh512() { ... }
128        DH *get_dh1024() { ... }
129
130        DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
131        {
132           DH *dh_tmp=NULL;
133
134           switch (keylength) {
135           case 512:
136             if (!dh_512)
137               dh_512 = get_dh512();
138             dh_tmp = dh_512;
139             break;
140           case 1024:
141             if (!dh_1024)
142               dh_1024 = get_dh1024();
143             dh_tmp = dh_1024;
144             break;
145           default:
146             /* Generating a key on the fly is very costly, so use what is there */
147             setup_dh_parameters_like_above();
148           }
149           return(dh_tmp);
150        }
151

RETURN VALUES

153       SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not
154       return diagnostic output.
155
156       SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
157       on failure. Check the error queue to find out the reason of failure.
158

NAME

SYNOPSIS

DESCRIPTION

NOTES

EXAMPLES

RETURN VALUES

SEE ALSO