Deprecate the low level Diffie-Hellman functions.
Use of the low level DH functions has been informally discouraged for a
long time. We now formally deprecate them.
Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/11024)
diff --git a/doc/man3/DH_generate_key.pod b/doc/man3/DH_generate_key.pod
index babc91f..35fcc02 100644
--- a/doc/man3/DH_generate_key.pod
+++ b/doc/man3/DH_generate_key.pod
@@ -8,12 +8,20 @@
#include <openssl/dh.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
int DH_generate_key(DH *dh);
int DH_compute_key(unsigned char *key, BIGNUM *pub_key, DH *dh);
=head1 DESCRIPTION
+Both of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_derive_init(3)>
+and L<EVP_PKEY_derive(3)>.
+
DH_generate_key() performs the first step of a Diffie-Hellman key
exchange by generating private and public DH values. By calling
DH_compute_key(), these are combined with the other party's public
@@ -40,8 +48,13 @@
=head1 SEE ALSO
+L<EVP_PKEY_derive(3)>,
L<DH_new(3)>, L<ERR_get_error(3)>, L<RAND_bytes(3)>, L<DH_size(3)>
+=head1 HISTORY
+
+Both of these functions were deprecated in OpenSSL 3.0.
+
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/DH_generate_parameters.pod b/doc/man3/DH_generate_parameters.pod
index 4908dcf..a01b940 100644
--- a/doc/man3/DH_generate_parameters.pod
+++ b/doc/man3/DH_generate_parameters.pod
@@ -12,6 +12,10 @@
#include <openssl/dh.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
int DH_generate_parameters_ex(DH *dh, int prime_len, int generator, BN_GENCB *cb);
int DH_check(DH *dh, int *codes);
@@ -30,6 +34,11 @@
=head1 DESCRIPTION
+All of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_check(3)>,
+L<EVP_PKEY_public_check(3)>, L<EVP_PKEY_private_check(3)> and
+L<EVP_PKEY_param_check(3)>.
+
DH_generate_parameters_ex() generates Diffie-Hellman parameters that can
be shared among a group of users, and stores them in the provided B<DH>
structure. The pseudo-random number generator must be
@@ -144,6 +153,8 @@
=head1 HISTORY
+All of these functions were deprecated in OpenSSL 3.0.
+
DH_generate_parameters() was deprecated in OpenSSL 0.9.8; use
DH_generate_parameters_ex() instead.
diff --git a/doc/man3/DH_get0_pqg.pod b/doc/man3/DH_get0_pqg.pod
index 4883b67..ab49a32 100644
--- a/doc/man3/DH_get0_pqg.pod
+++ b/doc/man3/DH_get0_pqg.pod
@@ -26,6 +26,11 @@
void DH_clear_flags(DH *dh, int flags);
int DH_test_flags(const DH *dh, int flags);
void DH_set_flags(DH *dh, int flags);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
ENGINE *DH_get0_engine(DH *d);
long DH_get_length(const DH *dh);
int DH_set_length(DH *dh, long length);
@@ -78,12 +83,13 @@
within the DH object.
DH_get0_engine() returns a handle to the ENGINE that has been set for this DH
-object, or NULL if no such ENGINE has been set.
+object, or NULL if no such ENGINE has been set. This function is deprecated.
The DH_get_length() and DH_set_length() functions get and set the optional
length parameter associated with this DH object. If the length is nonzero then
it is used, otherwise it is ignored. The B<length> parameter indicates the
-length of the secret exponent (private key) in bits.
+length of the secret exponent (private key) in bits. These functions are
+deprecated.
=head1 NOTES
@@ -114,6 +120,9 @@
=head1 HISTORY
+The DH_get0_engine(), DH_get_length() and DH_set_length() functions were
+deprecated in OpenSSL 3.0.
+
The functions described here were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
diff --git a/doc/man3/DH_meth_new.pod b/doc/man3/DH_meth_new.pod
index 652abaa..38c3bd3 100644
--- a/doc/man3/DH_meth_new.pod
+++ b/doc/man3/DH_meth_new.pod
@@ -14,6 +14,10 @@
#include <openssl/dh.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
DH_METHOD *DH_meth_new(const char *name, int flags);
void DH_meth_free(DH_METHOD *dhm);
@@ -58,6 +62,9 @@
=head1 DESCRIPTION
+All of the functions described on this page are deprecated.
+Applications should instead use the provider APIs.
+
The B<DH_METHOD> type is a structure used for the provision of custom DH
implementations. It provides a set of functions used by OpenSSL for the
implementation of the various DH capabilities.
@@ -153,6 +160,8 @@
=head1 HISTORY
+All of these functions were deprecated in OpenSSL 3.0.
+
The functions described here were added in OpenSSL 1.1.0.
=head1 COPYRIGHT
diff --git a/doc/man3/DH_new_by_nid.pod b/doc/man3/DH_new_by_nid.pod
index 5fd71ff..3456b9d 100644
--- a/doc/man3/DH_new_by_nid.pod
+++ b/doc/man3/DH_new_by_nid.pod
@@ -8,6 +8,11 @@
#include <openssl/dh.h>
DH *DH_new_by_nid(int nid);
+
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
int *DH_get_nid(DH *dh);
=head1 DESCRIPTION
@@ -18,10 +23,9 @@
B<NID_modp_1536>, B<NID_modp_2048>, B<NID_modp_3072>,
B<NID_modp_4096>, B<NID_modp_6144> or B<NID_modp_8192>.
-
DH_get_nid() determines if the parameters contained in B<dh> match
any named set. It returns the NID corresponding to the matching parameters or
-B<NID_undef> if there is no match.
+B<NID_undef> if there is no match. This function is deprecated.
=head1 RETURN VALUES
@@ -30,6 +34,10 @@
DH_get_nid() returns the NID of the matching set of parameters or
B<NID_undef> if there is no match.
+=head1 HISTORY
+
+The DH_get_nid() function was deprecated in OpenSSL 3.0.
+
=head1 COPYRIGHT
Copyright 2017-2020 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/DH_set_method.pod b/doc/man3/DH_set_method.pod
index 8c7713d..ae3d8fa 100644
--- a/doc/man3/DH_set_method.pod
+++ b/doc/man3/DH_set_method.pod
@@ -9,6 +9,10 @@
#include <openssl/dh.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
void DH_set_default_method(const DH_METHOD *meth);
const DH_METHOD *DH_get_default_method(void);
@@ -21,6 +25,9 @@
=head1 DESCRIPTION
+All of the functions described on this page are deprecated.
+Applications should instead use the provider APIs.
+
A B<DH_METHOD> specifies the functions that OpenSSL uses for Diffie-Hellman
operations. By modifying the method, alternative implementations
such as hardware accelerators may be used. IMPORTANT: See the NOTES section for
@@ -76,6 +83,10 @@
L<DH_new(3)>, L<DH_new(3)>, L<DH_meth_new(3)>
+=head1 HISTORY
+
+All of these functions were deprecated in OpenSSL 3.0.
+
=head1 COPYRIGHT
Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/doc/man3/DH_size.pod b/doc/man3/DH_size.pod
index 3161ef3..8a206f0 100644
--- a/doc/man3/DH_size.pod
+++ b/doc/man3/DH_size.pod
@@ -9,6 +9,10 @@
#include <openssl/dh.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
int DH_size(const DH *dh);
int DH_bits(const DH *dh);
@@ -17,6 +21,10 @@
=head1 DESCRIPTION
+All of the functions described on this page are deprecated.
+Applications should instead use L<EVP_PKEY_bits(3)>,
+L<EVP_PKEY_security_bits(3)> and L<EVP_PKEY_size(3)>.
+
DH_size() returns the Diffie-Hellman prime size in bytes. It can be used
to determine how much memory must be allocated for the shared secret
computed by L<DH_compute_key(3)>.
@@ -38,11 +46,14 @@
=head1 SEE ALSO
+L<EVP_PKEY_bits(3)>,
L<DH_new(3)>, L<DH_generate_key(3)>,
L<BN_num_bits(3)>
=head1 HISTORY
+All of these functions were deprecated in OpenSSL 3.0.
+
The DH_bits() function was added in OpenSSL 1.1.0.
=head1 COPYRIGHT
diff --git a/doc/man3/DSA_dup_DH.pod b/doc/man3/DSA_dup_DH.pod
index baaca6d..897d9a1 100644
--- a/doc/man3/DSA_dup_DH.pod
+++ b/doc/man3/DSA_dup_DH.pod
@@ -8,10 +8,18 @@
#include <openssl/dsa.h>
+Deprecated since OpenSSL 3.0, can be hidden entirely by defining
+B<OPENSSL_API_COMPAT> with a suitable version value, see
+L<openssl_user_macros(7)>:
+
DH *DSA_dup_DH(const DSA *r);
=head1 DESCRIPTION
+The function described on this page is deprecated. There is no direct
+replacement, applications should use the EVP_PKEY APIs for Diffie-Hellman
+operations.
+
DSA_dup_DH() duplicates DSA parameters/keys as DH parameters/keys. q
is lost during that conversion, but the resulting DH parameters
contain its length.
@@ -29,6 +37,10 @@
L<DH_new(3)>, L<DSA_new(3)>, L<ERR_get_error(3)>
+=head1 HISTORY
+
+This function was deprecated in OpenSSL 3.0.
+
=head1 COPYRIGHT
Copyright 2000-2018 The OpenSSL Project Authors. All Rights Reserved.
