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 1c8e94966918951dc2925a9318e6c055d82a1fcd..ac5e7bd125ef2b6fd6cf8903fac2d83d057b4fb7 100644 (file)
--- 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.