aboutsummaryrefslogtreecommitdiffstats
path: root/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
diff options
context:
space:
mode:
Diffstat (limited to 'doc/ssl/SSL_CTX_set_tmp_dh_callback.pod')
-rw-r--r--doc/ssl/SSL_CTX_set_tmp_dh_callback.pod130
1 files changed, 0 insertions, 130 deletions
diff --git a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod b/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
deleted file mode 100644
index 234fbc845002..000000000000
--- a/doc/ssl/SSL_CTX_set_tmp_dh_callback.pod
+++ /dev/null
@@ -1,130 +0,0 @@
-=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.
-
-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() 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. */
- }
- ...
-
-=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