Deprecated EVP_PKEY_CTX_get0_dh_kdf_ukm() and EVP_PKEY_CTX_get0_ecdh_kdf_ukm()

The functions are not needed and require returning octet ptr parameters
from providers that would like to support them which complicates provider
implementations.

Fixes #12985

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/14279)

diff --git a/CHANGES.md b/CHANGES.md
index 0e9f27824c2bfe6cdd1a3f93478e8224b1bdc8d7..c7a2c0baa5ea9c7575ccf8f14b6a221ed4f3ae39 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -22,15 +22,20 @@ OpenSSL 3.0
 -----------
 
 ### Changes between 1.1.1 and 3.0 [xx XXX xxxx]
+ * Deprecated obsolete EVP_PKEY_CTX_get0_dh_kdf_ukm() and
+   EVP_PKEY_CTX_get0_ecdh_kdf_ukm() functions. They are not needed
+   and require returning octet ptr parameters from providers that
+   would like to support them which complicates provider implementations.
 
-* The RAND_METHOD APIs have been deprecated.  The functions deprecated are:
+   *Tomáš Mráz*
+
+ * The RAND_METHOD APIs have been deprecated.  The functions deprecated are:
    RAND_OpenSSL(), RAND_get_rand_method(), RAND_set_rand_engine() and
    RAND_set_rand_method().  Provider based random number generators should
    be used instead via EVP_RAND(3).
 
    *Paul Dale*
-
-* The SRP APIs have been deprecated. The old APIs do not work via providers,
+ * The SRP APIs have been deprecated. The old APIs do not work via providers,
    and there is no EVP interface to them. Unfortunately there is no replacement
    for these APIs at this time.
 
@@ -41,7 +46,7 @@ OpenSSL 3.0
    at configuration time.
 
    *Paul Dale*
- 
+
  * Combining the Configure options no-ec and no-dh no longer disables TLSv1.3.
    Typically if OpenSSL has no EC or DH algorithms then it cannot support
    connections with TLSv1.3. However OpenSSL now supports "pluggable" groups

diff --git a/crypto/evp/dh_ctrl.c b/crypto/evp/dh_ctrl.c
index abb724f72b998957ce1852fd6c2b052f1c651a20..7eb0a8ee48575598d7b47f54070620af6ab33e8b 100644 (file)
--- a/crypto/evp/dh_ctrl.c
+++ b/crypto/evp/dh_ctrl.c
@@ -7,6 +7,8 @@
  * https://www.openssl.org/source/license.html
  */
 
+#include "internal/deprecated.h"
+
 #include <stdio.h>
 #include <string.h>
 #include <openssl/core_names.h>
@@ -322,6 +324,7 @@ int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len)
     return ret;
 }
 
+#ifndef OPENSSL_NO_DEPRECATED_3_0
 int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **pukm)
 {
     int ret;
@@ -348,3 +351,4 @@ int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **pukm)
 
     return (int)ukmlen;
 }
+#endif

diff --git a/crypto/evp/ec_ctrl.c b/crypto/evp/ec_ctrl.c
index 17f1a8f28882b9e643b5a39c4029e6c1824b13ee..ff0c55d0232098c9182ed72b637ae7054f4c9a79 100644 (file)
--- a/crypto/evp/ec_ctrl.c
+++ b/crypto/evp/ec_ctrl.c
@@ -243,6 +243,7 @@ int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int le
     return ret;
 }
 
+#ifndef OPENSSL_NO_DEPRECATED_3_0
 int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **pukm)
 {
     size_t ukmlen;
@@ -283,6 +284,7 @@ int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **pukm)
 
     return ret;
 }
+#endif
 
 #ifndef FIPS_MODULE
 /*

diff --git a/doc/man3/EVP_PKEY_CTX_ctrl.pod b/doc/man3/EVP_PKEY_CTX_ctrl.pod
index 1de332c3b3eb8adbf4edb59808a59cb32bb9703d..54e4f5506e508b64b8e4b80ce5cd2613ad3e2c67 100644 (file)
--- a/doc/man3/EVP_PKEY_CTX_ctrl.pod
+++ b/doc/man3/EVP_PKEY_CTX_ctrl.pod
@@ -157,7 +157,6 @@ EVP_PKEY_CTX_set_kem_op
  int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
  int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
  int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
- int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
 
  #include <openssl/ec.h>
 
@@ -172,7 +171,6 @@ EVP_PKEY_CTX_set_kem_op
  int EVP_PKEY_CTX_set_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
  int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
  int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
- int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
 
  int EVP_PKEY_CTX_set1_id(EVP_PKEY_CTX *ctx, void *id, size_t id_len);
  int EVP_PKEY_CTX_get1_id(EVP_PKEY_CTX *ctx, void *id);
@@ -186,6 +184,14 @@ L<openssl_user_macros(7)>:
 
  int EVP_PKEY_CTX_set_rsa_keygen_pubexp(EVP_PKEY_CTX *ctx, BIGNUM *pubexp);
 
+ #include <openssl/dh.h>
+
+ int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
+
+ #include <openssl/ec.h>
+
+ int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
+
 =head1 DESCRIPTION
 
 EVP_PKEY_CTX_ctrl() sends a control operation to the context I<ctx>. The key
@@ -669,6 +675,9 @@ added in OpenSSL 1.0.0.
 In OpenSSL 1.1.1 and below the functions were mostly macros.
 From OpenSSL 3.0 they are all functions.
 
+EVP_PKEY_CTX_set_rsa_keygen_pubexp(), EVP_PKEY_CTX_get0_dh_kdf_ukm(),
+and EVP_PKEY_CTX_get0_ecdh_kdf_ukm() were deprecated in OpenSSL 3.0.
+
 =head1 COPYRIGHT
 
 Copyright 2006-2020 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/EVP_KEYEXCH-DH.pod b/doc/man7/EVP_KEYEXCH-DH.pod
index 9e9cee7dce0e4eee35feecb54cf7e76e12d51221..4368c62140ac7c9a2fa4f7634d6c75ce61e0ac3b 100644 (file)
--- a/doc/man7/EVP_KEYEXCH-DH.pod
+++ b/doc/man7/EVP_KEYEXCH-DH.pod
@@ -17,6 +17,19 @@ Key exchange support for the B<DH> key type.
 
 See L<provider-keyexch(7)/Common Key Exchange parameters>.
 
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string>
+
+Sets the User Key Material to be used as part of the selected Key Derivation
+Function associated with the given key exchange ctx.
+
+=item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
+
+Gets a pointer to the User Key Material to be used as part of the selected
+Key Derivation Function associated with the given key exchange ctx. Providers
+usually do not need to support this gettable parameter as its sole purpose
+is to support functionality of the deprecated EVP_PKEY_CTX_get0_dh_kdf_ukm()
+function.
+
 =back
 
 =head1 EXAMPLES

diff --git a/doc/man7/EVP_KEYEXCH-ECDH.pod b/doc/man7/EVP_KEYEXCH-ECDH.pod
index 5ad6801263ca721cb5ecce40a1b6485bd5781f5e..001df6ba0c64a7c216f28252e0c7a6e4ef82b5e0 100644 (file)
--- a/doc/man7/EVP_KEYEXCH-ECDH.pod
+++ b/doc/man7/EVP_KEYEXCH-ECDH.pod
@@ -60,7 +60,10 @@ Function associated with the given key exchange ctx.
 =item "kdf-ukm" (B<OSSL_EXCHANGE_PARAM_KDF_UKM>) <octet_string_ptr>
 
 Gets a pointer to the User Key Material to be used as part of the selected
-Key Derivation Function associated with the given key exchange ctx.
+Key Derivation Function associated with the given key exchange ctx. Providers
+usually do not need to support this gettable parameter as its sole purpose
+is to support functionality of the deprecated EVP_PKEY_CTX_get0_ecdh_kdf_ukm()
+function.
 
 =back
 

diff --git a/include/openssl/core_names.h b/include/openssl/core_names.h
index a9ab57dbff04a17fb2f969ab77aab3085b3f7c5c..cb8d83ba88ad00737953070a016431c4405c3f84 100644 (file)
--- a/include/openssl/core_names.h
+++ b/include/openssl/core_names.h
@@ -432,20 +432,8 @@ extern "C" {
 #define OSSL_EXCHANGE_PARAM_KDF_DIGEST            "kdf-digest" /* utf8_string */
 #define OSSL_EXCHANGE_PARAM_KDF_DIGEST_PROPS      "kdf-digest-props" /* utf8_string */
 #define OSSL_EXCHANGE_PARAM_KDF_OUTLEN            "kdf-outlen" /* size_t */
-
-/*
- * TODO(3.0): improve this pattern
- *
- * Currently the sole internal user of OSSL_EXCHANGE_PARAM_KDF_UKM is
- * EVP_PKEY_CTX_{set0,get0}_ecdh_kdf_ukm():
- *      OSSL_EXCHANGE_PARAM_KDF_UKM is handled as a octet_string on set0,
- *      and as an octet_ptr on get0.
- *
- * This pattern is borrowed from the handling of
- * OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL in
- * EVP_PKEY_CTX_{set0,get0}_rsa_oaep_label().
- */
-#define OSSL_EXCHANGE_PARAM_KDF_UKM               "kdf-ukm" /* see note above */
+/* The following parameter is an octet_string on set and an octet_ptr on get */
+#define OSSL_EXCHANGE_PARAM_KDF_UKM               "kdf-ukm"
 
 /* Signature parameters */
 #define OSSL_SIGNATURE_PARAM_ALGORITHM_ID       "algorithm-id"
@@ -469,6 +457,7 @@ extern "C" {
     OSSL_PKEY_PARAM_MGF1_PROPERTIES
 #define OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST              OSSL_ALG_PARAM_DIGEST
 #define OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS        "digest-props"
+/* The following parameter is an octet_string on set and an octet_ptr on get */
 #define OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL               "oaep-label"
 #define OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION       "tls-client-version"
 #define OSSL_ASYM_CIPHER_PARAM_TLS_NEGOTIATED_VERSION   "tls-negotiated-version"

diff --git a/include/openssl/dh.h b/include/openssl/dh.h
index 67ba0aa6875f3b54a2b68f63b2b311ae10691008..d17f01334fd279916e06f5aa2e665bb4971fc062 100644 (file)
--- a/include/openssl/dh.h
+++ b/include/openssl/dh.h
@@ -53,7 +53,10 @@ int EVP_PKEY_CTX_get_dh_kdf_md(EVP_PKEY_CTX *ctx, const EVP_MD **md);
 int EVP_PKEY_CTX_set_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int len);
 int EVP_PKEY_CTX_get_dh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
 int EVP_PKEY_CTX_set0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm, int len);
+# ifndef OPENSSL_NO_DEPRECATED_3_0
+OSSL_DEPRECATEDIN_3_0
 int EVP_PKEY_CTX_get0_dh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
+#endif
 
 # define EVP_PKEY_CTRL_DH_PARAMGEN_PRIME_LEN     (EVP_PKEY_ALG_CTRL + 1)
 # define EVP_PKEY_CTRL_DH_PARAMGEN_GENERATOR     (EVP_PKEY_ALG_CTRL + 2)

diff --git a/include/openssl/ec.h b/include/openssl/ec.h
index 5f93694f3514c7b2ff5aa30609e05f416b608861..c503954b9ce3abd2edfca6adeba4d842f4aabef8 100644 (file)
--- a/include/openssl/ec.h
+++ b/include/openssl/ec.h
@@ -44,7 +44,10 @@ int EVP_PKEY_CTX_get_ecdh_kdf_outlen(EVP_PKEY_CTX *ctx, int *len);
 
 int EVP_PKEY_CTX_set0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char *ukm,
                                    int len);
+# ifndef OPENSSL_NO_DEPRECATED_3_0
+OSSL_DEPRECATEDIN_3_0
 int EVP_PKEY_CTX_get0_ecdh_kdf_ukm(EVP_PKEY_CTX *ctx, unsigned char **ukm);
+# endif
 
 # define EVP_PKEY_CTRL_EC_PARAMGEN_CURVE_NID    (EVP_PKEY_ALG_CTRL + 1)
 # define EVP_PKEY_CTRL_EC_PARAM_ENC             (EVP_PKEY_ALG_CTRL + 2)

diff --git a/util/libcrypto.num b/util/libcrypto.num
index 25d86194715a020aea60345768c03ca5cc9a960c..0403a6944bdb6884efe45eeffb5bcb710f8ebcc6 100644 (file)
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -4900,7 +4900,7 @@ EVP_PKEY_CTX_get_ecdh_kdf_md            ? 3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_set_ecdh_kdf_outlen        ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_get_ecdh_kdf_outlen        ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_set0_ecdh_kdf_ukm          ?      3_0_0   EXIST::FUNCTION:
-EVP_PKEY_CTX_get0_ecdh_kdf_ukm          ?      3_0_0   EXIST::FUNCTION:
+EVP_PKEY_CTX_get0_ecdh_kdf_ukm          ?      3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3_0
 EVP_PKEY_CTX_set_rsa_pss_saltlen        ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_get_rsa_pss_saltlen        ?      3_0_0   EXIST::FUNCTION:
 d2i_ISSUER_SIGN_TOOL                    ?      3_0_0   EXIST::FUNCTION:
@@ -5186,7 +5186,7 @@ EVP_PKEY_CTX_get_dh_kdf_md              ? 3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_set_dh_kdf_outlen          ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_get_dh_kdf_outlen          ?      3_0_0   EXIST::FUNCTION:
 EVP_PKEY_CTX_set0_dh_kdf_ukm            ?      3_0_0   EXIST::FUNCTION:
-EVP_PKEY_CTX_get0_dh_kdf_ukm            ?      3_0_0   EXIST::FUNCTION:
+EVP_PKEY_CTX_get0_dh_kdf_ukm            ?      3_0_0   EXIST::FUNCTION:DEPRECATEDIN_3_0
 EVP_CIPHER_CTX_get_updated_iv           ?      3_0_0   EXIST::FUNCTION:
 EVP_CIPHER_CTX_get_original_iv          ?      3_0_0   EXIST::FUNCTION:
 EVP_KEYMGMT_gettable_params             ?      3_0_0   EXIST::FUNCTION: