146 lines
5 KiB
Text
146 lines
5 KiB
Text
=pod
|
|
|
|
=head1 NAME
|
|
|
|
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
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/ssl.h>
|
|
|
|
void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
|
|
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
|
|
long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);
|
|
|
|
void SSL_set_tmp_dh_callback(SSL_CTX *ctx,
|
|
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
|
|
long SSL_set_tmp_dh(SSL *ssl, DH *dh)
|
|
|
|
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
SSL_CTX_set_tmp_dh_callback() sets the callback function for B<ctx> to be
|
|
used when a DH parameters are required to B<tmp_dh_callback>.
|
|
The callback is inherited by all B<ssl> objects created from B<ctx>.
|
|
|
|
SSL_CTX_set_tmp_dh() sets DH parameters to be used to be B<dh>.
|
|
The key is inherited by all B<ssl> objects created from B<ctx>.
|
|
|
|
SSL_set_tmp_dh_callback() sets the callback only for B<ssl>.
|
|
|
|
SSL_set_tmp_dh() sets the paramters only for B<ssl>.
|
|
|
|
These functions apply to SSL/TLS servers only.
|
|
|
|
=head1 NOTES
|
|
|
|
When using a cipher with RSA authentication, an ephemeral DH key exchange
|
|
can take place. Ciphers with DSA keys always use ephemeral DH keys as well
|
|
as anonymous ciphers. In this case the session data are negotiated using the
|
|
ephemeral/temporary DH key and the key supplied and certified
|
|
by the certificate chain is only used for signing.
|
|
|
|
Using ephemeral DH key exchange yields forward secrecy, as the connection
|
|
can only be decrypted, when the DH key is known. By generating a temporary
|
|
DH key inside the server application that is lost when the application
|
|
is left, it becomes impossible for an attacker to decrypt past sessions,
|
|
even if he gets hold of the normal (certified) key, as this key was
|
|
only used for signing.
|
|
|
|
In order to perform a DH key exchange the server must use a DH group
|
|
(DH parameters) and generate a DH key. The server will automatically
|
|
generate the DH key when required, as it is computationally cheap
|
|
(retrieve a random number). The server will reuse the DH key for further
|
|
connections, unless the SSL_OP_SINGLE_DH_USE option of
|
|
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)> is set, in which case
|
|
a new DH key for each negotiation will be generated.
|
|
|
|
As generating DH parameters is extremely time consuming, an application
|
|
should not generate the parameters on the fly but supply the parameters.
|
|
DH parameters can be reused, as the actual key is newly generated during
|
|
the negotiation. The risk in reusing DH parameters is that an attacker
|
|
may specialize on a very often used DH group. Therefore application authors
|
|
should not copy the DH parameters from other applications or the OpenSSL
|
|
example application, if they compile in parameters, but generate their
|
|
own set of parameters using e.g. the openssl L<dhparam(1)|dhparam(1)>
|
|
application with the B<-C> option. An application may also generate
|
|
its own set of DH parameters during the installation procedure on a specific
|
|
host, so that each host uses different parameters.
|
|
|
|
An application my either directly specify the DH parameters or
|
|
can supply the DH parameters via a callback function. The callback approach
|
|
has the advantage, that the callback may supply DH parameters for different
|
|
key lengths.
|
|
|
|
The B<tmp_dh_callback> is called with the B<keylength> needed and
|
|
the B<is_export> information. The B<is_export> flag is set, when the
|
|
ephemeral DH key exchange is performed with an export cipher.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
|
|
partly left out.)
|
|
|
|
...
|
|
/* Set up ephemeral DH stuff */
|
|
DH *dh_512 = NULL;
|
|
DH *dh_1024 = NULL;
|
|
FILE *paramfile;
|
|
|
|
...
|
|
/* "openssl dhparam -out dh_param_512.pem -2 512" */
|
|
paramfile = fopen("dh_param_512.pem", "r");
|
|
if (paramfile) {
|
|
dh_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
|
|
fclose(paramfile);
|
|
}
|
|
/* "openssl dhparam -out dh_param_1024.pem -2 1024" */
|
|
paramfile = fopen("dh_param_1024.pem", "r");
|
|
if (paramfile) {
|
|
dh_1024 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
|
|
fclose(paramfile);
|
|
}
|
|
...
|
|
|
|
/* "openssl dhparam -C -2 512" etc... */
|
|
DH *get_dh512() { ... }
|
|
DH *get_dh1024() { ... }
|
|
|
|
DH *tmp_dh_callback(SSL *s, int is_export, int keylength)
|
|
{
|
|
DH *dh_tmp=NULL;
|
|
|
|
switch (keylength) {
|
|
case 512:
|
|
if (!dh_512)
|
|
dh_512 = get_dh512();
|
|
dh_tmp = dh_512;
|
|
break;
|
|
case 1024:
|
|
if (!dh_1024)
|
|
dh_1024 = get_dh1024();
|
|
dh_tmp = dh_1024;
|
|
break;
|
|
default:
|
|
/* Generating a key on the fly is very costly, so use what is there */
|
|
setup_dh_parameters_like_above();
|
|
}
|
|
return(dh_tmp);
|
|
}
|
|
|
|
=head1 RETURN VALUES
|
|
|
|
SSL_CTX_set_tmp_dh_callback() and SSL_set_tmp_dh_callback() do not return
|
|
diagnostic output.
|
|
|
|
SSL_CTX_set_tmp_dh() and SSL_set_tmp_dh() do return 1 on success and 0
|
|
on failure. Check the error queue to find out the reason of failure.
|
|
|
|
=head1 SEE ALSO
|
|
|
|
L<ssl(3)|ssl(3)>, L<SSL_CTX_set_cipher_list(3)|SSL_CTX_set_cipher_list(3)>,
|
|
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
|
|
L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
|
|
|
|
=cut
|