Commit 7d5d7628a5 for openssl.org
commit 7d5d7628a5bac55b7096b93df01d332d224f7623
Author: Dmitry Belyavskiy <beldmit@gmail.com>
Date: Fri Oct 2 16:20:35 2026 +0200
Add EVP_KDF_derive_SKEYs libcrypto API
Implement the public API for multi-key derivation:
- EVP_KDF_derive_SKEYs(): derive multiple keys/IVs in one operation
- EVP_KDF_CTX_get1_SKEY(): retrieve a derived key by purpose name
- EVP_KDF_CTX_get0_IV(): retrieve a derived IV by purpose name
The EVP_KDF_CTX is extended with a multi_skeymgmt field to hold the
skeymgmt used for wrapping provider keydata into EVP_SKEY objects.
Cleanup is handled in EVP_KDF_CTX_free, _reset, and _dup.
Also update the design document to remove get0_SKEY — only get1_SKEY
(caller-owned reference) is provided.
Assisted-By: Claude Opus 4.6 <noreply@anthropic.com>
Reviewed-by: Mounir Idrassi <mounir.idrassi@idrix.fr>
Reviewed-by: Simo Sorce <simo@redhat.com>
MergeDate: Wed Nov 18 12:11:47 2026
(Merged from https://github.com/openssl/openssl/pull/33082)
diff --git a/crypto/evp/kdf_lib.c b/crypto/evp/kdf_lib.c
index c89d93b3ba..42ea73de93 100644
--- a/crypto/evp/kdf_lib.c
+++ b/crypto/evp/kdf_lib.c
@@ -18,6 +18,7 @@
#include "crypto/evp.h"
#include "internal/numbers.h"
#include "internal/provider.h"
+#include "internal/sizes.h"
#include "evp_local.h"
#include "internal/param_build_set.h"
@@ -76,6 +77,11 @@ EVP_KDF_CTX *EVP_KDF_CTX_dup(const EVP_KDF_CTX *src)
EVP_KDF_CTX_free(dst);
return NULL;
}
+
+ /*
+ * The derived keys live in algctx and were copied by dupctx() above; a
+ * provider that cannot copy them fails there.
+ */
return dst;
}
@@ -296,6 +302,94 @@ EVP_SKEY *EVP_KDF_derive_SKEY(EVP_KDF_CTX *ctx, EVP_SKEYMGMT *mgmt,
EVP_SKEYMGMT_free(skeymgmt);
return ret;
}
+int EVP_KDF_derive_SKEYs(EVP_KDF_CTX *ctx, const OSSL_PARAM params[])
+{
+ if (ctx == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_PASSED_NULL_PARAMETER);
+ return 0;
+ }
+
+ if (ctx->meth->derive_multi == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_UNSUPPORTED);
+ return 0;
+ }
+
+ return ctx->meth->derive_multi(ctx->algctx, params);
+}
+
+EVP_SKEY *EVP_KDF_CTX_get1_SKEY(EVP_KDF_CTX *ctx, const char *purpose,
+ const char *propquery)
+{
+ EVP_SKEY *skey = NULL;
+ EVP_SKEYMGMT *skeymgmt;
+ char keytype[OSSL_MAX_NAME_SIZE] = "";
+ OSSL_PARAM p[2];
+ void *keydata;
+
+ if (ctx == NULL || purpose == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_PASSED_NULL_PARAMETER);
+ return NULL;
+ }
+
+ if (ctx->meth->get_skey == NULL
+ || ctx->meth->get_ctx_params == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_UNSUPPORTED);
+ return NULL;
+ }
+
+ /*
+ * Ask which key type this derivation produced for the purpose; each may
+ * use a different one, so the skeymgmt is resolved per call rather than
+ * once for the whole derivation. A purpose no key was derived for, such
+ * as a MAC key in an AEAD ciphersuite, is reported by the provider
+ * failing here.
+ */
+ p[0] = OSSL_PARAM_construct_utf8_string(purpose, keytype, sizeof(keytype));
+ p[1] = OSSL_PARAM_construct_end();
+ if (!ctx->meth->get_ctx_params(ctx->algctx, p) || keytype[0] == '\0') {
+ ERR_raise_data(ERR_LIB_EVP, EVP_R_INVALID_KEY,
+ "no key derived for purpose %s", purpose);
+ return NULL;
+ }
+
+ skeymgmt = evp_skeymgmt_fetch_from_prov(ctx->meth->prov, keytype,
+ propquery);
+ if (skeymgmt == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_FETCH_FAILED);
+ return NULL;
+ }
+
+ keydata = ctx->meth->get_skey(ctx->algctx, purpose,
+ ossl_provider_ctx(skeymgmt->prov), skeymgmt->import);
+
+ /* evp_skey_alloc() takes its own reference on the skeymgmt */
+ if (keydata != NULL && (skey = evp_skey_alloc(skeymgmt)) != NULL) {
+ skey->keydata = keydata;
+ } else if (keydata != NULL) {
+ /* evp_skey_alloc failed but keydata was allocated - free it */
+ skeymgmt->free(keydata);
+ }
+
+ EVP_SKEYMGMT_free(skeymgmt);
+
+ return skey;
+}
+
+int EVP_KDF_CTX_get0_IV(EVP_KDF_CTX *ctx, const char *purpose,
+ const unsigned char **pIV, size_t *pIVlen)
+{
+ if (ctx == NULL || purpose == NULL || pIV == NULL || pIVlen == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_PASSED_NULL_PARAMETER);
+ return 0;
+ }
+
+ if (ctx->meth->get_iv == NULL) {
+ ERR_raise(ERR_LIB_EVP, ERR_R_UNSUPPORTED);
+ return 0;
+ }
+
+ return ctx->meth->get_iv(ctx->algctx, purpose, pIV, pIVlen);
+}
#endif /* !FIPS_MODULE */
/*
diff --git a/doc/designs/evp_skey_multi.md b/doc/designs/evp_skey_multi.md
index 1e5413abba..7f25abb365 100644
--- a/doc/designs/evp_skey_multi.md
+++ b/doc/designs/evp_skey_multi.md
@@ -7,7 +7,8 @@ need to derive 2-4 keys, depending on the protocol version. With raw bytes
buffer, the approach was to derive a combined buffer of the necessary length
and chop it. It doesn't work this way for EVP_SKEY objects.
-This document proposes API and a general approach to deal with such situations.
+This document describes the API and the general approach used to deal with
+such situations.
Model use case
--------------
@@ -20,68 +21,127 @@ The API is designed from the perspective of being a transparent wrapper for
PKCS#11 mechanisms for simultaneous key generation and avoid the extra calls to
token API from the provider.
+The shape of the API follows `CKM_TLS12_KEY_AND_MAC_DERIVE` closely. Its
+`CK_TLS12_KEY_MAT_PARAMS` carries three sizes -- `ulMacSizeInBits`,
+`ulKeySizeInBits` and `ulIVSizeInBits` -- one per *kind* of output rather than
+one per direction, and its `CK_SSL3_KEY_MAT_OUT` returns four key handles
+alongside two plain IV buffers. Two consequences run through the whole design:
+sizes and key types are chosen per kind of key, because the two directions of a
+connection always agree on them; and IVs are not key objects.
+
Libcrypto API
-------------
-As all the objects are derived in one transaction, we can store a single opaque
-pointer keeping all the keys inside in the EVP_KDF_CTX object, and provide the
-API for access to a particular object.
+As all the objects are derived in one transaction, the provider derives them
+together and keeps them in its own context, and we provide the API for access
+to a particular object.
To derive the opaque keys and bytes buffers, we use the function
```C
-int EVP_KDF_derive_SKEYs(EVP_KDF_CTX *ctx, EVP_SKEYMGMT *mgmt,
- const char *propquery, const OSSL_PARAM params[]);
+int EVP_KDF_derive_SKEYs(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
```
-This function doesn't directly return objects when this functions succeeds,
-they are stored in the EVP_KDF_CTX object.
+This function doesn't directly return objects when it succeeds; they are held
+by the provider and discarded by the next derivation on the same context, or by
+`EVP_KDF_CTX_reset()` or `EVP_KDF_CTX_free()`.
The options that define key types and sizes, number of keys or IVs and their
-length can generally be specified by passing appropriate parameters in the
-`params` argument. If no params are provided, defaults may be used by specific
-KDF operations.
+length are specified by passing appropriate parameters in the `params`
+argument. If no params are provided, defaults may be used by specific KDF
+operations.
The params can also be set by a preceding call to `EVP_KDF_CTX_set_params`.
-To access the individual EVP_SKEY values, we introduce the functions
+The key type is not given as an EVP_SKEYMGMT name. Instead the caller names
+the algorithm the key is *for* -- the `"cipher"` and `"mac"` parameters, e.g.
+`"AES-128-CBC"` and `"HMAC"` -- and the provider decides which of its own key
+types that calls for. This is what allows a PKCS#11 provider to give an HMAC
+key a distinct type while the default provider treats it as a generic secret.
+A named cipher also states the length of its own key, so `"cipher_key_len"` is
+then unnecessary; a MAC does not, since for HMAC the length is a property of
+the TLS ciphersuite rather than of the algorithm, so `"mac_key_len"` is always
+given explicitly. The IV length is likewise explicit, because the IV in a TLS
+1.2 key block is whatever the protocol says it is -- for an AEAD suite the
+implicit nonce rather than the cipher's full IV.
+
+Validating the request is the provider's job and happens as part of the
+derivation, so a key length that disagrees with the cipher named for it is
+reported by `EVP_KDF_derive_SKEYs()` rather than later when the key is
+collected. This is also where a provider backed by a token naturally refuses
+a template, which is why the check belongs there rather than in libcrypto: an
+earlier revision had libcrypto build every key eagerly to catch the same
+mistake, but once the provider was given the cipher name it could check the
+length itself, and the eager pass had nothing left to catch.
+
+To access the individual EVP_SKEY values, we introduce the function
```C
-EVP_SKEY *EVP_KDF_CTX_get0_SKEY(EVP_KDF_CTX *ctx, const char *purpose);
-EVP_SKEY *EVP_KDF_CTX_get1_SKEY(EVP_KDF_CTX *ctx, const char *purpose);
+EVP_SKEY *EVP_KDF_CTX_get1_SKEY(EVP_KDF_CTX *ctx, const char *purpose,
+ const char *propquery);
```
where the `purpose` argument is a name of the particular EVP_SKEY purpose (e.g.
-"client_MAC_key", "server_CIPHER_key") as specified by the documentation of the
-specific KDF operation that was executed.
+"client_MAC_key", "server_cipher_key") as specified by the documentation of the
+specific KDF operation that was executed. The returned EVP_SKEY has its reference
+count incremented and must be freed by the caller. Each purpose carries its own
+key type, so the keys of one derivation need not all be alike; `propquery`
+selects the EVP_SKEYMGMT implementation for whichever type this one uses.
+
+A derivation may legitimately produce no key for some purpose the algorithm
+defines, in which case retrieving it fails: a TLS 1.2 key block for an AEAD
+ciphersuite contains no MAC keys.
-To access an IV, the proposed API is
+To access an IV, the API is
```C
int EVP_KDF_CTX_get0_IV(EVP_KDF_CTX *ctx, const char *purpose,
- unsigned char **pIV, size_t *pIVlen);
+ const unsigned char **pIV, size_t *pIVlen);
```
where the `purpose` argument is a documented name of the particular IV purpose
-(e.g. "client_IV") and `pIVlen` argument is a way to get the length of
-generated IV.
+(e.g. "client_iv") and `pIVlen` argument is a way to get the length of
+generated IV. IVs are not keys and are returned as raw bytes owned by the
+derivation result; the caller must not free them.
Provider API
------------
-We extend the EVP_KDF structure with the following member functions:
+The derived keys and IVs stay in the provider's own KDF context, beside the
+inputs they were derived from. An earlier revision had `derive_multi` return a
+separate result object that libcrypto owned, but that object needed its own
+free, dup and parameter accessors, each duplicating one the KDF context already
+had; keeping the results in the context removes all four.
```C
-OSSL_CORE_MAKE_FUNC(int, kdf_derive_multi, (void *kctx,
- const OSSL_PARAM params[]))
+OSSL_CORE_MAKE_FUNC(int, kdf_derive_multi,
+ (void *kctx, const OSSL_PARAM params[]))
-OSSL_CORE_MAKE_FUNC(int, kdf_get_skey,
- (void *kctx, void *skeydata, const char *purpose, bool incr_refcount))
-
-OSSL_CORE_MAKE_FUNC(unsigned char *, kdf_get_iv,
- (void *kctx, const char *purpose))
+OSSL_CORE_MAKE_FUNC(void *, kdf_get_skey,
+ (void *kctx, const char *purpose, void *provctx,
+ OSSL_FUNC_skeymgmt_import_fn *import))
+OSSL_CORE_MAKE_FUNC(int, kdf_get_iv,
+ (void *kctx, const char *purpose,
+ const unsigned char **pIV, size_t *pIVlen))
```
+`kdf_freectx` releases the derived keys along with the rest of the context and
+`kdf_dupctx` copies them; a provider whose keys exist only as handles on a token
+and cannot be copied fails the latter, so that a caller never receives a context
+that has silently lost its keys.
+
+The key type settled on for each purpose is reported through the ordinary
+`kdf_get_ctx_params`, in a parameter named after that purpose, and that call
+fails for a purpose no key was produced for — which is how libcrypto learns a
+slot is absent. Resolving the type this way, rather than fixing one
+EVP_SKEYMGMT for the whole derivation, is what permits an AES cipher key and a
+generic-secret MAC key to come out of the same call.
+
+`kdf_get_skey` receives the import function of the EVP_SKEYMGMT libcrypto
+resolved from the reported type. A provider that already holds the key as a
+native object may ignore it and return that object instead, so a token's keys
+never have to exist as raw bytes.
+
Providers may either imply some KDF-specific defaults when it's obvious from
the KDF specification or throw an error otherwise.
diff --git a/doc/man3/EVP_KDF.pod b/doc/man3/EVP_KDF.pod
index f2d890b70c..a65c0d1bdb 100644
--- a/doc/man3/EVP_KDF.pod
+++ b/doc/man3/EVP_KDF.pod
@@ -6,6 +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_derive_SKEYs, EVP_KDF_CTX_get1_SKEY, EVP_KDF_CTX_get0_IV,
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,
@@ -34,6 +35,11 @@ EVP_KDF_CTX_gettable_params, EVP_KDF_CTX_settable_params - EVP KDF routines
EVP_SKEY *EVP_KDF_derive_SKEY(EVP_KDF_CTX *ctx, EVP_SKEYMGMT *mgmt,
const char *key_type, const char *propquery,
size_t keylen, const OSSL_PARAM params[]);
+ int EVP_KDF_derive_SKEYs(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
+ EVP_SKEY *EVP_KDF_CTX_get1_SKEY(EVP_KDF_CTX *ctx, const char *purpose,
+ const char *propquery);
+ int EVP_KDF_CTX_get0_IV(EVP_KDF_CTX *ctx, const char *purpose,
+ const unsigned char **pIV, size_t *pIVlen);
int EVP_KDF_up_ref(EVP_KDF *kdf);
void EVP_KDF_free(EVP_KDF *kdf);
EVP_KDF *EVP_KDF_fetch(OSSL_LIB_CTX *libctx, const char *algorithm,
@@ -136,6 +142,47 @@ key names, we can specify the particular parameter name we set. If null is
passed, the parameter B<OSSL_KDF_PARAM_KEY> is implied. It is used when the
input key is represented by B<EVP_SKEY> rather than raw bytes.
+EVP_KDF_derive_SKEYs() performs a multi-key derivation, producing several keys
+and IVs at once from a single KDF operation. This is what protocols such as
+TLS need: a TLS 1.2 key block yields client and server MAC keys, cipher keys
+and IVs from one PRF call. It also allows a provider holding its keys on a
+token to derive them all in a single operation and never expose the raw bytes.
+
+The derivation is described entirely by I<params>. Alongside the usual inputs
+of the KDF, these say how large each kind of output should be and which key
+type it should be produced as; the parameter names are algorithm specific and
+are listed with the individual KDFs, see L<EVP_KDF-TLS1_PRF(7)> and
+L<EVP_KDF-TLS13_KDF(7)>. A key type that the caller does not name takes a
+default chosen by the provider.
+
+The result is retained in I<ctx> and is discarded by the next call to
+EVP_KDF_derive_SKEYs(), or by EVP_KDF_CTX_reset() or EVP_KDF_CTX_free().
+Individual keys and IVs are collected with EVP_KDF_CTX_get1_SKEY() and
+EVP_KDF_CTX_get0_IV().
+
+The provider checks the sizes and types it was asked for as part of the
+derivation, so a request it cannot satisfy -- a key length that disagrees with
+the cipher named for it, say -- is reported by EVP_KDF_derive_SKEYs() rather
+than later when the key is collected.
+
+EVP_KDF_CTX_get1_SKEY() retrieves a derived key by I<purpose> string from a
+context on which EVP_KDF_derive_SKEYs() has been called. Each purpose carries
+its own key type, so the keys of one derivation need not all be alike. The
+caller receives an owned reference to the B<EVP_SKEY> and must free it with
+EVP_SKEY_free(). I<propquery> is used to fetch the B<EVP_SKEYMGMT> for the key
+type the derivation chose for this purpose.
+
+EVP_KDF_CTX_get0_IV() retrieves a derived IV by I<purpose> string from a
+context on which EVP_KDF_derive_SKEYs() has been called. IVs are not keys and
+are returned as raw bytes rather than as B<EVP_SKEY> objects. On success,
+I<*pIV> is set to a pointer to the IV data owned by the context (not a copy)
+and I<*pIVlen> to its length; the pointer remains valid until the derivation
+result is discarded.
+
+A derivation may legitimately produce no key for some purpose the algorithm
+defines, in which case retrieving it fails: a TLS 1.2 key block for an AEAD
+ciphersuite, for example, contains no MAC keys.
+
EVP_KDF_get_params() retrieves details about the implementation
I<kdf>.
The set of parameters given with I<params> determine exactly what
@@ -313,6 +360,9 @@ return value of 0 means that the callback was not called for any names.
EVP_KDF_derive_SKEY() returns the B<EVP_SKEY> object on success or NULL on failure.
+EVP_KDF_CTX_get1_SKEY() returns an owned B<EVP_SKEY> pointer on success or NULL
+on failure.
+
The remaining functions return 1 for success and 0 for failure.
=head1 NOTES
@@ -339,6 +389,9 @@ in OpenSSL 4.1.
EVP_KDF_CTX_kdf() function was deprecated in favour of EVP_KDF_CTX_get0_kdf()
in OpenSSL 4.1.
+EVP_KDF_derive_SKEYs(), EVP_KDF_CTX_get1_SKEY(), and EVP_KDF_CTX_get0_IV()
+were added in OpenSSL 4.2.
+
=head1 COPYRIGHT
Copyright 2019-2026 The OpenSSL Project Authors. All Rights Reserved.
diff --git a/include/openssl/kdf.h b/include/openssl/kdf.h
index aee4aa1bc6..abd552d089 100644
--- a/include/openssl/kdf.h
+++ b/include/openssl/kdf.h
@@ -53,6 +53,35 @@ int EVP_KDF_CTX_set_SKEY(EVP_KDF_CTX *ctx, EVP_SKEY *key, const char *paramname)
EVP_SKEY *EVP_KDF_derive_SKEY(EVP_KDF_CTX *ctx, EVP_SKEYMGMT *mgmt,
const char *key_type, const char *propquery,
size_t keylen, const OSSL_PARAM params[]);
+/**
+ * Perform multi-key derivation producing several keys and IVs in one operation
+ * @param ctx KDF context
+ * @param params parameters including key sizes and IV lengths
+ * @return 1 on success, 0 on failure
+ * @see EVP_KDF_derive_SKEYs(3)
+ */
+int EVP_KDF_derive_SKEYs(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
+/**
+ * Retrieve a derived key by purpose string from a preceding EVP_KDF_derive_SKEYs() call
+ * @param ctx KDF context
+ * @param purpose purpose string (e.g., OSSL_KDF_PURPOSE_CLIENT_KEY)
+ * @param propquery property query string (may be NULL)
+ * @return owned EVP_SKEY pointer on success, NULL if absent or on error
+ * @see EVP_KDF_CTX_get1_SKEY(3)
+ */
+EVP_SKEY *EVP_KDF_CTX_get1_SKEY(EVP_KDF_CTX *ctx, const char *purpose,
+ const char *propquery);
+/**
+ * Retrieve a derived IV by purpose string from a preceding EVP_KDF_derive_SKEYs() call
+ * @param ctx KDF context
+ * @param purpose purpose string (e.g., OSSL_KDF_PURPOSE_CLIENT_IV)
+ * @param pIV pointer to receive IV pointer (not owned by caller)
+ * @param pIVlen pointer to receive IV length
+ * @return 1 on success, 0 if absent or on error
+ * @see EVP_KDF_CTX_get0_IV(3)
+ */
+int EVP_KDF_CTX_get0_IV(EVP_KDF_CTX *ctx, const char *purpose,
+ const unsigned char **pIV, size_t *pIVlen);
int EVP_KDF_get_params(EVP_KDF *kdf, OSSL_PARAM params[]);
int EVP_KDF_CTX_get_params(EVP_KDF_CTX *ctx, OSSL_PARAM params[]);
int EVP_KDF_CTX_set_params(EVP_KDF_CTX *ctx, const OSSL_PARAM params[]);
diff --git a/util/libcrypto.num b/util/libcrypto.num
index f51053c5c7..2ae2b8f8c8 100644
--- a/util/libcrypto.num
+++ b/util/libcrypto.num
@@ -5748,5 +5748,8 @@ PKCS12_PARSE_CTX_set_cert ? 4_2_0 EXIST::FUNCTION:
PKCS12_PARSE_CTX_set_ca ? 4_2_0 EXIST::FUNCTION:
PKCS12_PARSE_CTX_set_skeys ? 4_2_0 EXIST::FUNCTION:
PKCS12_parse_ex ? 4_2_0 EXIST::FUNCTION:
+EVP_KDF_derive_SKEYs ? 4_2_0 EXIST::FUNCTION:
+EVP_KDF_CTX_get1_SKEY ? 4_2_0 EXIST::FUNCTION:
+EVP_KDF_CTX_get0_IV ? 4_2_0 EXIST::FUNCTION:
PKCS12_check_version ? 4_2_0 EXIST::FUNCTION:
CRYPTO_new_ex_data_ex ? 4_2_0 EXIST::FUNCTION: