HKDF updates

- prevent fixed-digest HKDF from having its digest changed
- implement gettable params in HKDF
- update fixed-digest HKDF tests

Reviewed-by: Shane Lontis <shane.lontis@oracle.com>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Paul Dale <ppzgs1@gmail.com>
(Merged from openssl#27247)

Author: danvangeest

CHANGES.md

@@ -112,7 +112,7 @@ OpenSSL 3.6
 
    *Dimitri John Ledkov*
 
- * HKDF with (SHA-256,SHA-384,SHA-512) has assigned OIDs. Added ability to load
+ * HKDF with (SHA-256, SHA-384, SHA-512) has assigned OIDs. Added ability to load
    HKDF configured with these explicit digests by name or OID.
 
    *Daniel Van Geest (CryptoNext Security)*

doc/man7/EVP_KDF-HKDF.pod

@@ -17,15 +17,6 @@ of the KDF).
 
 The output is considered to be keying material.
 
-=head2 Fixed-Digest HKDF
-
-B<HKDF-SHA256>, B<HKDF-SHA384> and B<HKDF-SHA512> are fixed-digest versions
-of the B<HKDF> algorithm. Each algorithm has its own OID. These algorithms
-are instantiated with the appropriate digest already configured, thus it is
-not necessary to set the digest using the B<OSSL_KDF_PARAM_DIGEST> parameter.
-An attempt to set the digest to anything other than the pre-configured digest
-will result in an error.
-
 =head2 Identity
 
 The following algorithms are available for this implementation; they
@@ -40,12 +31,20 @@ mere OID which came out in this form after a call to L<OBJ_obj2txt(3)>).
 
 =item "HKDF"
 
+The B<OSSL_KDF_PARAM_DIGEST> parameter must be set for B<HKDF> before it can
+be used.
+
 =item "HKDF-SHA256", "id-alg-hkdf-with-sha256", "1.2.840.113549.1.9.16.3.28"
 
 =item "HKDF-SHA384", "id-alg-hkdf-with-sha384", "1.2.840.113549.1.9.16.3.29"
 
 =item "HKDF-SHA512", "id-alg-hkdf-with-sha512", "1.2.840.113549.1.9.16.3.30"
 
+B<HKDF-SHA256>, B<HKDF-SHA384> and B<HKDF-SHA512> are fixed-digest versions
+of B<HKDF> with the appropriate digest already configured.
+L<EVP_KDF_CTX_reset(3)> will not reset the context's digest for fixed-digest
+versions.
+
 =back
 
 =head2 Supported parameters
@@ -58,6 +57,8 @@ The supported parameters are:
 
 =item "digest" (B<OSSL_KDF_PARAM_DIGEST>) <UTF8 string>
 
+Attempting to set the digest on a fixed-digest B<HKDF> will result in an error.
+
 =item "key" (B<OSSL_KDF_PARAM_KEY>) <octet string>
 
 =item "salt" (B<OSSL_KDF_PARAM_SALT>) <octet string>
@@ -84,8 +85,9 @@ up for HKDF will perform an extract followed by an expand operation in one go.
 The derived key returned will be the result after the expand operation. The
 intermediate fixed-length pseudorandom key K is not returned.
 
-In this mode the digest, key, salt and info values must be set before a key is
-derived otherwise an error will occur.
+In this mode the key, salt and info values must be set before a key is
+derived otherwise an error will occur. For non-fixed mode (B<HKDF>) the digest
+must also be set.
 
 =item "EXTRACT_ONLY" or B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY>
 
@@ -94,17 +96,19 @@ operation. The value returned will be the intermediate fixed-length pseudorandom
 key K.  The I<keylen> parameter must match the size of K, which can be looked
 up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest.
 
-The digest, key and salt values must be set before a key is derived otherwise
-an error will occur.
+The key and salt values must be set before a key is derived otherwise
+an error will occur. For non-fixed mode (B<HKDF>) the digest
+must also be set.
 
 =item "EXPAND_ONLY" or B<EVP_KDF_HKDF_MODE_EXPAND_ONLY>
 
 In this mode calling L<EVP_KDF_derive(3)> will just perform the expand
 operation. The input key should be set to the intermediate fixed-length
 pseudorandom key K returned from a previous extract operation.
 
-The digest, key and info values must be set before a key is derived otherwise
-an error will occur.
+The key and info values must be set before a key is derived otherwise
+an error will occur. For non-fixed mode (B<HKDF>) the digest
+must also be set.
 
 =back
 
@@ -148,6 +152,8 @@ after setting the mode and digest on the B<EVP_KDF_CTX>.
 
 =head1 EXAMPLES
 
+=head2 HKDF Algorithm
+
 This example derives 10 bytes using SHA-256 with the secret key "secret",
 salt value "salt" and info value "label":
 
@@ -175,6 +181,33 @@ salt value "salt" and info value "label":
 
  EVP_KDF_CTX_free(kctx);
 
+=head2 HKDF-SHA256 Algorithm
+
+This example derives 10 bytes using HKDF-SHA256 with the secret key "secret",
+salt value "salt" and info value "label":
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[4], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "HKDF-SHA256", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
+                                          "secret", (size_t)6);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_INFO,
+                                          "label", (size_t)5);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+                                          "salt", (size_t)4);
+ *p = OSSL_PARAM_construct_end();
+ if (EVP_KDF_derive(kctx, out, sizeof(out), params) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
 =head1 CONFORMING TO
 
 RFC 5869 and RFC 8619

doc/man7/OSSL_PROVIDER-FIPS.pod

@@ -588,7 +588,7 @@ L<https://www.openssl.org/source/>
 
 =head1 HISTORY
 
-The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 digests were added in OpenSSL 3.6.
+The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 algorithms were added in OpenSSL 3.6.
 
 All other functionality was added in OpenSSL 3.0.
 

doc/man7/OSSL_PROVIDER-default.pod

@@ -530,7 +530,7 @@ L<OSSL_PROVIDER-base(7)>
 
 The RIPEMD160 digest was added to the default provider in OpenSSL 3.0.7.
 
-The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 digests were added in OpenSSL 3.6.
+The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 algorithms were added in OpenSSL 3.6.
 
 All other functionality was added in OpenSSL 3.0.
 

providers/defltprov.c

@@ -398,9 +398,6 @@ static const OSSL_ALGORITHM deflt_keyexch[] = {
 #endif
     { PROV_NAMES_TLS1_PRF, "provider=default", ossl_kdf_tls1_prf_keyexch_functions },
     { PROV_NAMES_HKDF, "provider=default", ossl_kdf_hkdf_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA256, "provider=default", ossl_kdf_hkdf_sha256_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA384, "provider=default", ossl_kdf_hkdf_sha384_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA512, "provider=default", ossl_kdf_hkdf_sha512_keyexch_functions },
     { PROV_NAMES_SCRYPT, "provider=default",
       ossl_kdf_scrypt_keyexch_functions },
     { NULL, NULL, NULL }
@@ -589,12 +586,6 @@ static const OSSL_ALGORITHM deflt_keymgmt[] = {
       PROV_DESCS_TLS1_PRF_SIGN },
     { PROV_NAMES_HKDF, "provider=default", ossl_kdf_keymgmt_functions,
       PROV_DESCS_HKDF_SIGN },
-    { PROV_NAMES_HKDF_SHA256, "provider=default", ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA256_SIGN },
-    { PROV_NAMES_HKDF_SHA384, "provider=default", ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA384_SIGN },
-    { PROV_NAMES_HKDF_SHA512, "provider=default", ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA512_SIGN },
     { PROV_NAMES_SCRYPT, "provider=default", ossl_kdf_keymgmt_functions,
       PROV_DESCS_SCRYPT_SIGN },
     { PROV_NAMES_HMAC, "provider=default", ossl_mac_legacy_keymgmt_functions,

providers/fips/fipsprov.c

@@ -448,9 +448,6 @@ static const OSSL_ALGORITHM fips_keyexch[] = {
     { PROV_NAMES_TLS1_PRF, FIPS_DEFAULT_PROPERTIES,
       ossl_kdf_tls1_prf_keyexch_functions },
     { PROV_NAMES_HKDF, FIPS_DEFAULT_PROPERTIES, ossl_kdf_hkdf_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA256, FIPS_DEFAULT_PROPERTIES, ossl_kdf_hkdf_sha256_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA384, FIPS_DEFAULT_PROPERTIES, ossl_kdf_hkdf_sha384_keyexch_functions },
-    { PROV_NAMES_HKDF_SHA512, FIPS_DEFAULT_PROPERTIES, ossl_kdf_hkdf_sha512_keyexch_functions },
     { NULL, NULL, NULL }
 };
 
@@ -618,12 +615,6 @@ static const OSSL_ALGORITHM fips_keymgmt[] = {
       PROV_DESCS_TLS1_PRF_SIGN },
     { PROV_NAMES_HKDF, FIPS_DEFAULT_PROPERTIES, ossl_kdf_keymgmt_functions,
       PROV_DESCS_HKDF_SIGN },
-    { PROV_NAMES_HKDF_SHA256, FIPS_DEFAULT_PROPERTIES, ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA256_SIGN },
-    { PROV_NAMES_HKDF_SHA384, FIPS_DEFAULT_PROPERTIES, ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA384_SIGN },
-    { PROV_NAMES_HKDF_SHA512, FIPS_DEFAULT_PROPERTIES, ossl_kdf_keymgmt_functions,
-      PROV_DESCS_HKDF_SHA512_SIGN },
     { PROV_NAMES_HMAC, FIPS_DEFAULT_PROPERTIES, ossl_mac_legacy_keymgmt_functions,
       PROV_DESCS_HMAC_SIGN },
 #ifndef OPENSSL_NO_CMAC

providers/implementations/exchange/kdf_exch.c

@@ -79,9 +79,6 @@ static void *kdf_newctx(const char *kdfname, void *provctx)
 
 KDF_NEWCTX(tls1_prf, "TLS1-PRF")
 KDF_NEWCTX(hkdf, "HKDF")
-KDF_NEWCTX(hkdf_sha256, "HKDF-SHA256")
-KDF_NEWCTX(hkdf_sha384, "HKDF-SHA384")
-KDF_NEWCTX(hkdf_sha512, "HKDF-SHA512")
 KDF_NEWCTX(scrypt, "SCRYPT")
 
 static int kdf_init(void *vpkdfctx, void *vkdf, const OSSL_PARAM params[])
@@ -209,9 +206,6 @@ static const OSSL_PARAM *kdf_settable_ctx_params(ossl_unused void *vpkdfctx,
 
 KDF_SETTABLE_CTX_PARAMS(tls1_prf, "TLS1-PRF")
 KDF_SETTABLE_CTX_PARAMS(hkdf, "HKDF")
-KDF_SETTABLE_CTX_PARAMS(hkdf_sha256, "HKDF-SHA256")
-KDF_SETTABLE_CTX_PARAMS(hkdf_sha384, "HKDF-SHA384")
-KDF_SETTABLE_CTX_PARAMS(hkdf_sha512, "HKDF-SHA512")
 KDF_SETTABLE_CTX_PARAMS(scrypt, "SCRYPT")
 
 static const OSSL_PARAM *kdf_gettable_ctx_params(ossl_unused void *vpkdfctx,
@@ -240,9 +234,6 @@ static const OSSL_PARAM *kdf_gettable_ctx_params(ossl_unused void *vpkdfctx,
 
 KDF_GETTABLE_CTX_PARAMS(tls1_prf, "TLS1-PRF")
 KDF_GETTABLE_CTX_PARAMS(hkdf, "HKDF")
-KDF_GETTABLE_CTX_PARAMS(hkdf_sha256, "HKDF-SHA256")
-KDF_GETTABLE_CTX_PARAMS(hkdf_sha384, "HKDF-SHA384")
-KDF_GETTABLE_CTX_PARAMS(hkdf_sha512, "HKDF-SHA512")
 KDF_GETTABLE_CTX_PARAMS(scrypt, "SCRYPT")
 
 #define KDF_KEYEXCH_FUNCTIONS(funcname) \
@@ -263,7 +254,4 @@ KDF_GETTABLE_CTX_PARAMS(scrypt, "SCRYPT")
 
 KDF_KEYEXCH_FUNCTIONS(tls1_prf)
 KDF_KEYEXCH_FUNCTIONS(hkdf)
-KDF_KEYEXCH_FUNCTIONS(hkdf_sha256)
-KDF_KEYEXCH_FUNCTIONS(hkdf_sha384)
-KDF_KEYEXCH_FUNCTIONS(hkdf_sha512)
 KDF_KEYEXCH_FUNCTIONS(scrypt)