ff4de7dde9
- Do not advise generation of DH parameters with dsaparam to save computation time. - Promote use of custom parameters more, and explicitly forbid use of built-in parameters weaker than 2048 bits. - Advise the callback to ignore <keylength> - it is currently called with 1024 bits, but this value can and should be safely ignored by servers. Reviewed-by: Rich Salz <rsalz@openssl.org>
149 lines
5.8 KiB
Text
149 lines
5.8 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,
|
|
DH *(*tmp_dh_callback)(SSL *ssl, int is_export, int keylength));
|
|
long SSL_set_tmp_dh(SSL *ssl, DH *dh)
|
|
|
|
=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 parameters 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.
|
|
In these cases, 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.
|
|
Anonymous ciphers (without a permanent server key) also use ephemeral DH keys.
|
|
|
|
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 always generate a new DH key during the negotiation
|
|
if either the DH parameters are supplied via callback or the
|
|
SSL_OP_SINGLE_DH_USE option of SSL_CTX_set_options(3) is set (or both).
|
|
It will immediately create a DH key if DH parameters are supplied via
|
|
SSL_CTX_set_tmp_dh() and SSL_OP_SINGLE_DH_USE is not set.
|
|
In this case,
|
|
it may happen that a key is generated on initialization without later
|
|
being needed, while on the other hand the computer time during the
|
|
negotiation is being saved.
|
|
|
|
If "strong" primes were used to generate the DH parameters, it is not strictly
|
|
necessary to generate a new key for each handshake but it does improve forward
|
|
secrecy. If it is not assured that "strong" primes were used,
|
|
SSL_OP_SINGLE_DH_USE must be used in order to prevent small subgroup
|
|
attacks. Always using SSL_OP_SINGLE_DH_USE has an impact on the
|
|
computer time needed during negotiation, but it is not very large, so
|
|
application authors/users should consider always enabling this option.
|
|
The option is required to implement perfect forward secrecy (PFS).
|
|
|
|
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. Applications should therefore
|
|
generate their own DH parameters during the installation process using the
|
|
openssl L<dhparam(1)|dhparam(1)> application. This application
|
|
guarantees that "strong" primes are used.
|
|
|
|
Files dh2048.pem, and dh4096.pem in the 'apps' directory of the current
|
|
version of the OpenSSL distribution contain the 'SKIP' DH parameters,
|
|
which use safe primes and were generated verifiably pseudo-randomly.
|
|
These files can be converted into C code using the B<-C> option of the
|
|
L<dhparam(1)|dhparam(1)> application. Generation of custom DH
|
|
parameters during installation should still be preferred to stop an
|
|
attacker from specializing on a commonly used group. Files dh1024.pem
|
|
and dh512.pem contain old parameters that must not be used by
|
|
applications.
|
|
|
|
An application may either directly specify the DH parameters or
|
|
can supply the DH parameters via a callback function.
|
|
|
|
Previous versions of the callback used B<is_export> and B<keylength>
|
|
parameters to control parameter generation for export and non-export
|
|
cipher suites. Modern servers that do not support export ciphersuites
|
|
are advised to either use SSL_CTX_set_tmp_dh() in combination with
|
|
SSL_OP_SINGLE_DH_USE, or alternatively, use the callback but ignore
|
|
B<keylength> and B<is_export> and simply supply at least 2048-bit
|
|
parameters in the callback.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
Setup DH parameters with a key length of 2048 bits. (Error handling
|
|
partly left out.)
|
|
|
|
Command-line parameter generation:
|
|
$ openssl dhparam -out dh_param_2048.pem 2048
|
|
|
|
Code for setting up parameters during server initialization:
|
|
|
|
...
|
|
SSL_CTX ctx = SSL_CTX_new();
|
|
...
|
|
|
|
/* Set up ephemeral DH parameters. */
|
|
DH *dh_2048 = NULL;
|
|
FILE *paramfile;
|
|
paramfile = fopen("dh_param_2048.pem", "r");
|
|
if (paramfile) {
|
|
dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
|
|
fclose(paramfile);
|
|
} else {
|
|
/* Error. */
|
|
}
|
|
if (dh_2048 == NULL) {
|
|
/* Error. */
|
|
}
|
|
if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
|
|
/* Error. */
|
|
}
|
|
SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE);
|
|
...
|
|
|
|
=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_tmp_rsa_callback(3)|SSL_CTX_set_tmp_rsa_callback(3)>,
|
|
L<SSL_CTX_set_options(3)|SSL_CTX_set_options(3)>,
|
|
L<ciphers(1)|ciphers(1)>, L<dhparam(1)|dhparam(1)>
|
|
|
|
=cut
|