Add EVP_KDF_CTX_get0_kdf and EVP_KDF_CTX_get1_kdf, deprecate EVP_KDF_CTX_kdf

Resolves: https://github.com/openssl/openssl/issues/28327

Reviewed-by: Bob Beck <beck@openssl.org>
Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
MergeDate: Thu Jul  2 07:24:22 2026
(Merged from https://github.com/openssl/openssl/pull/28954)

diff --git a/CHANGES.md b/CHANGES.md
index ea505a94e5260adf4134fa7353e48d550a2b12a1..26ac778f555e6f5082cdfbedb3040732ce3e2071 100644 (file)
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -199,6 +199,11 @@ OpenSSL Releases
 
    *Timo Keller*
 
+ * Added `EVP_KDF_CTX_get0_kdf()` and `EVP_KDF_CTX_get1_kdf()` functions
+   as a replacement for the now deprecated `EVP_KDF_CTX_kdf()`.
+
+   *Leon Timmermans*
+
  * Add `FIPS_mode()` as a convenience define to
    `EVP_default_properties_is_fips_enabled(NULL)`, which is
    shorthand to check whether the `fips=yes` property is currently enabled

diff --git a/crypto/evp/kdf_lib.c b/crypto/evp/kdf_lib.c
index 4c9894299259038cf84fb56c86d1c113c149947d..67351044fba01ffed94da3087db1f861ac9ef0c4 100644 (file)
--- a/crypto/evp/kdf_lib.c
+++ b/crypto/evp/kdf_lib.c
@@ -104,11 +104,25 @@ const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf)
     return kdf->prov;
 }
 
-const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx)
+const EVP_KDF *EVP_KDF_CTX_get0_kdf(const EVP_KDF_CTX *ctx)
 {
     return ctx->meth;
 }
 
+#if !defined(OPENSSL_NO_DEPRECATED_4_1)
+const EVP_KDF *EVP_KDF_CTX_kdf(const EVP_KDF_CTX *ctx)
+{
+    return EVP_KDF_CTX_get0_kdf(ctx);
+}
+#endif /* !OPENSSL_NO_DEPRECATED_4_1 */
+
+EVP_KDF *EVP_KDF_CTX_get1_kdf(const EVP_KDF_CTX *ctx)
+{
+    if (!EVP_KDF_up_ref(ctx->meth))
+        return NULL;
+    return ctx->meth;
+}
+
 void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx)
 {
     if (ctx == NULL)

diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index b9cc14eb79d0ff9dde1005d1a76d8e0f88184010..6df44e86434157adddc4e70396fe861cf45db65b 100644 (file)
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -6,7 +6,7 @@ EVP_KDF, EVP_KDF_fetch, EVP_KDF_free, EVP_KDF_up_ref,
 EVP_KDF_CTX, EVP_KDF_CTX_new, EVP_KDF_CTX_free, EVP_KDF_CTX_dup,
 EVP_KDF_CTX_reset, EVP_KDF_derive,
 EVP_KDF_CTX_set_SKEY, EVP_KDF_derive_SKEY,
-EVP_KDF_CTX_get_kdf_size,
+EVP_KDF_CTX_get_kdf_size, EVP_KDF_CTX_get0_kdf, EVP_KDF_CTX_get1_kdf,
 EVP_KDF_get0_provider, EVP_KDF_CTX_kdf, EVP_KDF_is_a,
 EVP_KDF_get0_name, EVP_KDF_names_do_all, EVP_KDF_get0_description,
 EVP_KDF_CTX_get_params, EVP_KDF_CTX_set_params, EVP_KDF_do_all_provided,
@@ -22,7 +22,8 @@ EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
  typedef struct evp_kdf_ctx_st EVP_KDF_CTX;
 
  EVP_KDF_CTX *EVP_KDF_CTX_new(EVP_KDF *kdf);
- const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
+ const EVP_KDF *EVP_KDF_CTX_get0_kdf(const EVP_KDF_CTX *ctx);
+ EVP_KDF *EVP_KDF_CTX_get1_kdf(EVP_KDF_CTX *ctx);
  void EVP_KDF_CTX_free(EVP_KDF_CTX *ctx);
  EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src);
  void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx);
@@ -57,6 +58,12 @@ EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
  const OSSL_PARAM *EVP_KDF_CTX_settable_params(const EVP_KDF *kdf);
  const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);
 
+The following functions have been deprecated since OpenSSL 4.1,
+and can be hidden entirely by defining B<OPENSSL_API_COMPAT> with a suitable
+version value, see L<openssl_user_macros(7)>:
+
+ const EVP_KDF *EVP_KDF_CTX_kdf(const EVP_KDF_CTX *ctx);
+
 =head1 DESCRIPTION
 
 The EVP KDF routines are a high-level interface to Key Derivation Function
@@ -99,8 +106,10 @@ EVP_KDF_CTX_new() creates a new context for the KDF implementation I<kdf>.
 EVP_KDF_CTX_free() frees up the context I<ctx>.  If I<ctx> is NULL, nothing
 is done.
 
-EVP_KDF_CTX_kdf() returns the B<EVP_KDF> associated with the context
-I<ctx>.
+EVP_KDF_CTX_get0_kdf() returns the B<EVP_KDF> associated with the context
+I<ctx>. EVP_KDF_CTX_get1_kdf() is the same, except ownership is passed
+to the caller.
+EVP_KDF_CTX_kdf() is an alias for EVP_KDF_CTX_get0_kdf().
 
 =head2 Computing functions
 
@@ -324,6 +333,12 @@ This functionality was added in OpenSSL 3.0.
 EVP_KDF_derive_SKEY() and EVP_KDF_CTX_set_SKEY() functions were introduced in
 OpenSSL 3.6.
 
+EVP_KDF_CTX_get0_kdf() and EVP_KDF_CTX_get1_kdf() functions were introduced
+in OpenSSL 4.1.
+
+EVP_KDF_CTX_kdf() function was deprecated in favour of EVP_KDF_CTX_get0_kdf()
+in OpenSSL 4.1.
+
 =head1 COPYRIGHT
 
 Copyright 2019-2025 The OpenSSL Project Authors. All Rights Reserved.

diff --git a/doc/man7/ossl-guide-migration.pod b/doc/man7/ossl-guide-migration.pod
index 2c690dc48e83dc01aa484e9bc58ebbb98048f955..bf5c57d617ae919319cf2434cbda9135ca599807 100644 (file)
--- a/doc/man7/ossl-guide-migration.pod
+++ b/doc/man7/ossl-guide-migration.pod
@@ -38,6 +38,12 @@ ASN1_BIT_STRING_set1(). The new functions in addition to what
 ASN1_BIT_STRING_set() does, validates the function arguments and sets
 unused bits after setting the BIT STRING value.
 
+=head3 Deprecation of EVP_KDF_CTX_kdf()
+
+This function is deprecated in favour of EVP_KDF_CTX_get0_ctx(), to align
+with the naming of functions that provide similar functionality for other kinds
+of EVP context oobjects.
+
 =head1 OPENSSL 4.0
 
 =head2 Main Changes from OpenSSL 3.6

diff --git a/include/openssl/kdf.h b/include/openssl/kdf.h
index ab79e02e043677cb93344801b2ffe8b0415f918a..d49b22373e803a9c2adf0b56ee91d47c673c448b 100644 (file)
--- a/include/openssl/kdf.h
+++ b/include/openssl/kdf.h
@@ -37,7 +37,13 @@ const char *EVP_KDF_get0_description(const EVP_KDF *kdf);
 int EVP_KDF_is_a(const EVP_KDF *kdf, const char *name);
 const char *EVP_KDF_get0_name(const EVP_KDF *kdf);
 const OSSL_PROVIDER *EVP_KDF_get0_provider(const EVP_KDF *kdf);
-const EVP_KDF *EVP_KDF_CTX_kdf(EVP_KDF_CTX *ctx);
+const EVP_KDF *EVP_KDF_CTX_get0_kdf(const EVP_KDF_CTX *ctx);
+EVP_KDF *EVP_KDF_CTX_get1_kdf(const EVP_KDF_CTX *ctx);
+
+#if !defined(OPENSSL_NO_DEPRECATED_4_1)
+OSSL_DEPRECATEDIN_4_1_FOR("Use EVP_KDF_CTX_get0_kdf")
+const EVP_KDF *EVP_KDF_CTX_kdf(const EVP_KDF_CTX *ctx);
+#endif /* !OPENSSL_NO_DEPRECATED_4_1 */
 
 void EVP_KDF_CTX_reset(EVP_KDF_CTX *ctx);
 size_t EVP_KDF_CTX_get_kdf_size(EVP_KDF_CTX *ctx);

diff --git a/test/evp_test.c b/test/evp_test.c
index ef359a72ef70f192376ddc4d80c97e52a6c723c8..77029f40db9b9da1a31dfb75b8741cd9781e69af 100644 (file)
--- a/test/evp_test.c
+++ b/test/evp_test.c
@@ -4151,7 +4151,7 @@ static int kdf_test_ctrl(EVP_TEST *t, EVP_KDF_CTX *kctx,
     KDF_DATA *kdata = t->data;
     int rv;
     char *p, *name;
-    const OSSL_PARAM *defs = EVP_KDF_settable_ctx_params(EVP_KDF_CTX_kdf(kctx));
+    const OSSL_PARAM *defs = EVP_KDF_settable_ctx_params(EVP_KDF_CTX_get0_kdf(kctx));
 
     if (!TEST_ptr(name = OPENSSL_strdup(value)))
         return 0;

diff --git a/util/libcrypto.num b/util/libcrypto.num
index 777dfbf70e7b9d5dbd0e952dd1ebc4fe018ed6bd..a51b72cf939bfe507bd70aba48d68300aa9e6c72 100644 (file)
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -1616,7 +1616,7 @@ EVP_KDF_get0_description                1614      4_0_0   EXIST::FUNCTION:
 EVP_KDF_is_a                            1615   4_0_0   EXIST::FUNCTION:
 EVP_KDF_get0_name                       1616   4_0_0   EXIST::FUNCTION:
 EVP_KDF_get0_provider                   1617   4_0_0   EXIST::FUNCTION:
-EVP_KDF_CTX_kdf                         1618   4_0_0   EXIST::FUNCTION:
+EVP_KDF_CTX_kdf                         1618   4_0_0   EXIST::FUNCTION:DEPRECATEDIN_4_1
 EVP_KDF_CTX_reset                       1619   4_0_0   EXIST::FUNCTION:
 EVP_KDF_CTX_get_kdf_size                1620   4_0_0   EXIST::FUNCTION:
 EVP_KDF_derive                          1621   4_0_0   EXIST::FUNCTION:
@@ -5722,3 +5722,5 @@ CRYPTO_atomic_cmp_exch_ptr              ? 4_1_0   EXIST::FUNCTION:
 EVP_EC_affine2oct                       ?      4_1_0   EXIST::FUNCTION:
 OPENSSL_sk_set_copy_thunks              ?      4_1_0   EXIST::FUNCTION:
 ASN1_STRING_new_not_owned               ?      4_1_0   EXIST::FUNCTION:
+EVP_KDF_CTX_get0_kdf                    ?      4_1_0   EXIST::FUNCTION:
+EVP_KDF_CTX_get1_kdf                    ?      4_1_0   EXIST::FUNCTION:

diff --git a/util/other.syms b/util/other.syms
index fa54186811dad4502375d9815425425bcf1d5296..564704dd8737927642a3bade6f9e2a63250e086a 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -314,6 +314,7 @@ ERR_raise                               define
 ERR_raise_data                          define
 EVP_DigestSignUpdate                    define
 EVP_DigestVerifyUpdate                  define
+EVP_KDF_CTX_kdf                         define
 EVP_MD_CTX_get_block_size               define
 EVP_MD_CTX_get0_name                    define
 EVP_MD_CTX_get_size                     define