diff options
Diffstat (limited to 'secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3')
| -rw-r--r-- | secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 | 112 |
1 files changed, 46 insertions, 66 deletions
diff --git a/secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 b/secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 index 4d80acd..c2c5c4b 100644 --- a/secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 +++ b/secure/lib/libssl/man/SSL_CTX_set_tmp_dh_callback.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.30) +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30) .\" .\" Standard preamble: .\" ======================================================================== @@ -133,7 +133,7 @@ .\" ======================================================================== .\" .IX Title "SSL_CTX_set_tmp_dh_callback 3" -.TH SSL_CTX_set_tmp_dh_callback 3 "2015-03-19" "1.0.1m" "OpenSSL" +.TH SSL_CTX_set_tmp_dh_callback 3 "2015-06-11" "1.0.1n" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -197,12 +197,12 @@ negotiation is being saved. .PP If \*(L"strong\*(R" primes were used to generate the \s-1DH\s0 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 \*(L"strong\*(R" primes were used (see especially -the section about \s-1DSA\s0 parameters below), \s-1SSL_OP_SINGLE_DH_USE\s0 must be used -in order to prevent small subgroup attacks. Always using \s-1SSL_OP_SINGLE_DH_USE\s0 -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 \*(L"strong\*(R" primes were used, +\&\s-1SSL_OP_SINGLE_DH_USE\s0 must be used in order to prevent small subgroup +attacks. Always using \s-1SSL_OP_SINGLE_DH_USE\s0 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 (\s-1PFS\s0). .PP As generating \s-1DH\s0 parameters is extremely time consuming, an application should not generate the parameters on the fly but supply the parameters. @@ -210,82 +210,62 @@ should not generate the parameters on the fly but supply the parameters. the negotiation. The risk in reusing \s-1DH\s0 parameters is that an attacker may specialize on a very often used \s-1DH\s0 group. Applications should therefore generate their own \s-1DH\s0 parameters during the installation process using the -openssl \fIdhparam\fR\|(1) application. In order to reduce the computer -time needed for this generation, it is possible to use \s-1DSA\s0 parameters -instead (see \fIdhparam\fR\|(1)), but in this case \s-1SSL_OP_SINGLE_DH_USE\s0 -is mandatory. +openssl \fIdhparam\fR\|(1) application. This application +guarantees that \*(L"strong\*(R" primes are used. .PP -Application authors may compile in \s-1DH\s0 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 '\s-1SKIP\s0' \s-1DH\s0 parameters, which use safe primes and were generated verifiably pseudo-randomly. These files can be converted into C code using the \fB\-C\fR option of the -\&\fIdhparam\fR\|(1) application. -Authors may also generate their own set of parameters using -\&\fIdhparam\fR\|(1), but a user may not be sure how the parameters were -generated. The generation of \s-1DH\s0 parameters during installation is therefore -recommended. +\&\fIdhparam\fR\|(1) application. Generation of custom \s-1DH\s0 +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. .PP An application may either directly specify the \s-1DH\s0 parameters or -can supply the \s-1DH\s0 parameters via a callback function. The callback approach -has the advantage, that the callback may supply \s-1DH\s0 parameters for different -key lengths. +can supply the \s-1DH\s0 parameters via a callback function. .PP -The \fBtmp_dh_callback\fR is called with the \fBkeylength\fR needed and -the \fBis_export\fR information. The \fBis_export\fR flag is set, when the -ephemeral \s-1DH\s0 key exchange is performed with an export cipher. +Previous versions of the callback used \fBis_export\fR and \fBkeylength\fR +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 \fISSL_CTX_set_tmp_dh()\fR in combination with +\&\s-1SSL_OP_SINGLE_DH_USE,\s0 or alternatively, use the callback but ignore +\&\fBkeylength\fR and \fBis_export\fR and simply supply at least 2048\-bit +parameters in the callback. .SH "EXAMPLES" .IX Header "EXAMPLES" -Handle \s-1DH\s0 parameters for key lengths of 512 and 1024 bits. (Error handling +Setup \s-1DH\s0 parameters with a key length of 2048 bits. (Error handling partly left out.) .PP -.Vb 5 -\& ... -\& /* Set up ephemeral DH stuff */ -\& DH *dh_512 = NULL; -\& DH *dh_1024 = NULL; -\& FILE *paramfile; +.Vb 2 +\& 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(); \& ... -\& /* "openssl dhparam \-out dh_param_512.pem \-2 512" */ -\& paramfile = fopen("dh_param_512.pem", "r"); +\& +\& /* 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); +\& ... .Ve .SH "RETURN VALUES" .IX Header "RETURN VALUES" |
