[openssl-commits] [openssl] master update
Emilia Kasper
emilia at openssl.org
Wed May 20 13:44:47 UTC 2015
The branch master has been updated
via 1554d55318a7bb3347f4ccfadf78cca56e51ee79 (commit)
via 1f302db3e70f50f9b5e0860581a18e117eafcf20 (commit)
via b5a379aae5e05d18a17e41cd7591a038e21395eb (commit)
from 5a1d2509060da8ca99fa41135eff7bf3a193f69f (commit)
- Log -----------------------------------------------------------------
commit 1554d55318a7bb3347f4ccfadf78cca56e51ee79
Author: Emilia Kasper <emilia at openssl.org>
Date: Mon May 18 13:57:01 2015 +0200
Remove dh512.pem
Reviewed-by: Rich Salz <rsalz at openssl.org>
commit 1f302db3e70f50f9b5e0860581a18e117eafcf20
Author: Emilia Kasper <emilia at openssl.org>
Date: Tue May 12 16:10:05 2015 +0200
Update documentation with Diffie-Hellman best practices.
- 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 at openssl.org>
commit b5a379aae5e05d18a17e41cd7591a038e21395eb
Author: Emilia Kasper <emilia at openssl.org>
Date: Wed May 13 12:05:41 2015 +0200
dhparam: fix documentation
The default bitlength is now 2048. Also clarify that either the number
of bits or the generator must be present:
$ openssl dhparam -2
and
$ openssl dhparam 2048
generate parameters but
$ openssl dhparam
does not.
Reviewed-by: Matt Caswell <matt at openssl.org>
-----------------------------------------------------------------------
Summary of changes:
apps/dh512.pem | 9 ---
doc/apps/dhparam.pod | 13 ++--
doc/ssl/SSL_CTX_set_tmp_dh_callback.pod | 104 +++++++++++++-------------------
3 files changed, 49 insertions(+), 77 deletions(-)
delete mode 100644 apps/dh512.pem
diff --git a/apps/dh512.pem b/apps/dh512.pem
deleted file mode 100644
index 200d16c..0000000
--- a/apps/dh512.pem
+++ /dev/null
@@ -1,9 +0,0 @@
------BEGIN DH PARAMETERS-----
-MEYCQQD1Kv884bEpQBgRjXyEpwpy1obEAxnIByl6ypUM2Zafq9AKUJsCRtMIPWak
-XUGfnHy9iUsiGSa6q6Jew1XpKgVfAgEC
------END DH PARAMETERS-----
-
-These are the 512 bit DH parameters from "Assigned Number for SKIP Protocols"
-(http://www.skip-vpn.org/spec/numbers.html).
-See there for how they were generated.
-Note that g is not a generator, but this is not a problem since p is a safe prime.
diff --git a/doc/apps/dhparam.pod b/doc/apps/dhparam.pod
index 6e27cf5..1cd4c76 100644
--- a/doc/apps/dhparam.pod
+++ b/doc/apps/dhparam.pod
@@ -71,8 +71,10 @@ check if the parameters are valid primes and generator.
=item B<-2>, B<-5>
-The generator to use, either 2 or 5. 2 is the default. If present then the
-input file is ignored and parameters are generated instead.
+The generator to use, either 2 or 5. If present then the
+input file is ignored and parameters are generated instead. If not
+present but B<numbits> is present, parameters are generated with the
+default generator 2.
=item B<-rand> I<file(s)>
@@ -85,9 +87,10 @@ all others.
=item I<numbits>
this option specifies that a parameter set should be generated of size
-I<numbits>. It must be the last option. If not present then a value of 512
-is used. If this option is present then the input file is ignored and
-parameters are generated instead.
+I<numbits>. It must be the last option. If this option is present then
+the input file is ignored and parameters are generated instead. If
+this option is not present but a generator (B<-2> or B<-5>) is
+present, parameters are generated with a default length of 2048 bits.
=item B<-noout>
diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
index a9995fc..64c8b65 100644
--- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
+++ b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
@@ -61,12 +61,11 @@ 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 (see especially
-the section about DSA parameters below), 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 to always enable
-this option.
+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
@@ -75,82 +74,61 @@ 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. In order to reduce the computer
-time needed for this generation, it is possible to use DSA parameters
-instead (see L<dhparam(1)|dhparam(1)>), but in this case SSL_OP_SINGLE_DH_USE
-is mandatory.
+openssl L<dhparam(1)|dhparam(1)> application. This application
+guarantees that "strong" primes are used.
-Application authors may compile in DH parameters. Files dh512.pem,
-dh1024.pem, dh2048.pem, and dh4096.pem in the 'apps' directory of current
+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.
-Authors may also generate their own set of parameters using
-L<dhparam(1)|dhparam(1)>, but a user may not be sure how the parameters were
-generated. The generation of DH parameters during installation is therefore
-recommended.
+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. File dh1024.pem
+contains 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. The callback approach
-has the advantage, that the callback may supply DH parameters for different
-key lengths.
+can supply the DH parameters via a callback function.
-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.
+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
-Handle DH parameters for key lengths of 512 and 1024 bits. (Error handling
+Setup DH parameters with a key length of 2048 bits. (Error handling
partly left out.)
- ...
- /* Set up ephemeral DH stuff */
- DH *dh_512 = NULL;
- DH *dh_1024 = NULL;
- FILE *paramfile;
+ Command-line parameter generation:
+ $ openssl dhparam -out dh_param_2048.pem 2048
+
+ Code for setting up parameters during server initialization:
...
- /* "openssl dhparam -out dh_param_512.pem -2 512" */
- paramfile = fopen("dh_param_512.pem", "r");
+ 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_512 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
+ dh_2048 = PEM_read_DHparams(paramfile, NULL, NULL, NULL);
fclose(paramfile);
+ } else {
+ /* Error. */
}
- /* "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);
+ if (dh_2048 == NULL) {
+ /* Error. */
}
- ...
-
- /* "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);
+ if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
+ /* Error. */
}
+ SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE);
+ ...
=head1 RETURN VALUES
More information about the openssl-commits
mailing list