From: Dmitry Belyavskiy <beldmit@gmail.com>
Date: Thu, 27 Jul 2023 10:12:40 +0000 (+0200)
Subject: Design document of using opaque object as symmetric key
X-Git-Tag: openssl-3.6.0-alpha1~12
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=034cd8389386cd1507d7c1430f17b86f89185d46;p=thirdparty%2Fopenssl.git

Design document of using opaque object as symmetric key

Signed-off-by: Dmitry Belyavskiy <beldmit@gmail.com>
Signed-off-by: Simo Sorce <simo@redhat.com>

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Neil Horman <nhorman@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/28369)
---

diff --git a/doc/designs/evp_skey.md b/doc/designs/evp_skey.md
index 1c8e9496691..ac5e7bd125e 100644
--- a/doc/designs/evp_skey.md
+++ b/doc/designs/evp_skey.md
@@ -144,5 +144,19 @@ similar to `EVP_MAC_init`
 API to derive an EVP_SKEY object
 --------------------------------
 
-This part is delayed for a while because the proposed API doesn't fit well with
-TLS KDFs deriving multiple keys simultaneously.
+The derived key can be algorithm-specific or algorithm-agnostic. To specify the
+algorithm binding, the params argument can be used.
+
+```C
+EVP_SKEY *EVP_PKEY_derive_SKEY(EVP_PKEY_CTX *ctx, EVP_SKEYMGMT *mgmt,
+                               const char *key_type, const char *propquery,
+                               size_t keylen, const OSSL_PARAM params[]);
+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[]);
+```
+
+similar to `EVP_PKEY_derive/EVP_KDF_derive`
+
+For some KDFs (e.g. TLS KDF, HKDF) we can derive several keys simultaneously.
+It requires a special API.