Update KDF documentation (section 7)

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/9662)

13 files changed, 811 insertions, 974 deletions

diff --git a/doc/man7/EVP_KDF-HKDF.pod b/doc/man7/EVP_KDF-HKDF.pod
new file mode 100644
index 0000000000..746e7fb972
--- /dev/null
+++ b/doc/man7/EVP_KDF-HKDF.pod
@@ -0,0 +1,154 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF-HKDF - The HKDF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<HKDF> KDF through the B<EVP_KDF> API.
+
+The EVP_KDF-HKDF algorithm implements the HKDF key derivation function.
+HKDF follows the "extract-then-expand" paradigm, where the KDF logically
+consists of two modules. The first stage takes the input keying material
+and "extracts" from it a fixed-length pseudorandom key K. The second stage
+"expands" the key K into several additional pseudorandom keys (the output
+of the KDF).
+
+=head2 Identity
+
+"HKDF" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
+
+=head2 Supported parameters
+
+The supported parameters are:
+
+=over 4
+
+=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
+
+=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
+
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
+
+=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
+
+This parameter sets the info value.
+The length of the context info buffer cannot exceed 1024 bytes;
+this should be more than enough for any normal use of HKDF.
+
+=item B<OSSL_KDF_PARAM_MODE> ("mode") <UTF8 string> or <int>
+
+This parameter sets the mode for the HKDF operation.
+There are three modes that are currently defined:
+
+=over 4
+
+=item B<EVP_KDF_HKDF_MODE_EXTRACT_AND_EXPAND> "EXTRACT_AND_EXPAND"
+
+This is the default mode.  Calling L<EVP_KDF-derive(3)> on an EVP_KDF_CTX set
+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.
+
+=item B<EVP_KDF_HKDF_MODE_EXTRACT_ONLY> "EXTRACT_ONLY"
+
+In this mode calling L<EVP_KDF-derive(3)> will just perform the extract
+operation. The value returned will be the intermediate fixed-length pseudorandom
+key K.  The C<keylen> parameter must match the size of K, which can be looked
+up by calling EVP_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.
+
+=item B<EVP_KDF_HKDF_MODE_EXPAND_ONLY> "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.
+
+=back
+
+=back
+
+=head1 NOTES
+
+A context for HKDF can be obtained by calling:
+
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
+
+The output length of an HKDF expand operation is specified via the C<keylen>
+parameter to the L<EVP_KDF-derive(3)> function.  When using
+EVP_KDF_HKDF_MODE_EXTRACT_ONLY the C<keylen> parameter must equal the size of
+the intermediate fixed-length pseudorandom key otherwise an error will occur.
+For that mode, the fixed output size can be looked up by calling EVP_KDF_size()
+after setting the mode and digest on the C<EVP_KDF_CTX>.
+
+=head1 EXAMPLES
+
+This example derives 10 bytes using SHA-256 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[5], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "HKDF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *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_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 5869
+
+=head1 SEE ALSO
+
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-size(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF-CTX(3)/PARAMETERS>
+
+=head1 COPYRIGHT
+
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KDF_PBKDF2.pod b/doc/man7/EVP_KDF-PBKDF2.pod
index e914f3713c..311e0a3769 100644
--- a/doc/man7/EVP_KDF_PBKDF2.pod
+++ b/doc/man7/EVP_KDF-PBKDF2.pod
@@ -2,46 +2,45 @@
 
 =head1 NAME
 
-EVP_KDF_PBKDF2 - The PBKDF2 EVP_KDF implementation
+EVP_KDF-PBKDF2 - The PBKDF2 EVP_KDF implementation
 
 =head1 DESCRIPTION
 
 Support for computing the B<PBKDF2> password-based KDF through the B<EVP_KDF>
 API.
 
-The EVP_KDF_PBKDF2 algorithm implements the PBKDF2 password-based key
+The EVP_KDF-PBKDF2 algorithm implements the PBKDF2 password-based key
 derivation function, as described in SP800-132; it derives a key from a password
 using a salt and iteration count.
 
-=head2 Numeric identity
+=head2 Identity
 
-B<EVP_KDF_PBKDF2> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
+"PBKDF2" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
 
-=head2 Supported controls
+=head2 Supported parameters
 
-The supported controls are:
+The supported parameters are:
 
 =over 4
 
-=item B<EVP_KDF_CTRL_SET_PASS>
+=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
 
-=item B<EVP_KDF_CTRL_SET_SALT>
+=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
 
-=item B<EVP_KDF_CTRL_SET_ITER>
+=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned int>
 
-This control has a default value of 2048.
+This parameter has a default value of 2048.
 
-=item B<EVP_KDF_CTRL_SET_MD>
+=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
 
-=item B<EVP_KDF_CTRL_SET_PBKDF2_PKCS5_MODE>
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
 
-This control expects one argument: C<int mode>
-
-This control can be used to enable or disable SP800-132 compliance checks.
+=item B<OSSL_KDF_PARAM_PKCS5> ("pkcs5") <int>
 
+This parameter can be used to enable or disable SP800-132 compliance checks.
 Setting the mode to 0 enables the compliance checks.
 
 The checks performed are:
@@ -59,8 +58,6 @@ The checks performed are:
 The default provider uses a default mode of 1 for backwards compatibility,
 and the fips provider uses a default mode of 0.
 
-EVP_KDF_ctrl_str() type string: "pkcs5"
-
 The value string is expected to be a decimal number 0 or 1.
 
 =back
@@ -84,12 +81,12 @@ SP800-132
 
 =head1 SEE ALSO
 
-L<EVP_KDF_CTX>,
-L<EVP_KDF_CTX_new_id(3)>,
-L<EVP_KDF_CTX_free(3)>,
-L<EVP_KDF_ctrl(3)>,
-L<EVP_KDF_derive(3)>,
-L<EVP_KDF_CTX(3)/CONTROLS>
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF-CTX(3)/PARAMETERS>
 
 =head1 HISTORY
 
diff --git a/doc/man7/EVP_KDF_SCRYPT.pod b/doc/man7/EVP_KDF-SCRYPT.pod
index aa50164e06..ce22aaa7ca 100644
--- a/doc/man7/EVP_KDF_SCRYPT.pod
+++ b/doc/man7/EVP_KDF-SCRYPT.pod
@@ -2,14 +2,14 @@
 
 =head1 NAME
 
-EVP_KDF_SCRYPT - The scrypt EVP_KDF implementation
+EVP_KDF-SCRYPT - The scrypt EVP_KDF implementation
 
 =head1 DESCRIPTION
 
 Support for computing the B<scrypt> password-based KDF through the B<EVP_KDF>
 API.
 
-The EVP_KDF_SCRYPT algorithm implements the scrypt password-based key
+The EVP_KDF-SCRYPT algorithm implements the scrypt password-based key
 derivation function, as described in RFC 7914.  It is memory-hard in the sense
 that it deliberately requires a significant amount of RAM for efficient
 computation. The intention of this is to render brute forcing of passwords on
@@ -32,40 +32,32 @@ GHz), this computation takes about 3 seconds. When N, r or p are not specified,
 they default to 1048576, 8, and 1, respectively. The maximum amount of RAM that
 may be used by scrypt defaults to 1025 MiB.
 
-=head2 Numeric identity
+=head2 Identity
 
-B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
+"ID-SCRYPT" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
 
-=head2 Supported controls
+=head2 Supported parameters
 
-The supported controls are:
+The supported parameters are:
 
 =over 4
 
-=item B<EVP_KDF_CTRL_SET_PASS>
+=item B<OSSL_KDF_PARAM_PASSWORD> ("pass") <octet string>
 
-=item B<EVP_KDF_CTRL_SET_SALT>
+=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
 
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
 
-=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
+=item B<OSSL_KDF_PARAM_SCRYPT_N> ("n") <int>
 
-=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
+=item B<OSSL_KDF_PARAM_SCRYPT_R> ("r") <int>
 
-=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
+=item B<OSSL_KDF_PARAM_SCRYPT_P> ("p") <int>
 
-B<EVP_KDF_CTRL_SET_SCRYPT_N> expects one argument: C<uint64_t N>
-
-B<EVP_KDF_CTRL_SET_SCRYPT_R> expects one argument: C<uint32_t r>
-
-B<EVP_KDF_CTRL_SET_SCRYPT_P> expects one argument: C<uint32_t p>
-
-These controls configure the scrypt work factors N, r and p.
-
-EVP_KDF_ctrl_str() type strings: "N", "r" and "p", respectively.
-
-The corresponding value strings are expected to be decimal numbers.
+These parameters configure the scrypt work factors N, r and p.
+N is a parameter of type uint64_t.
+Both r and p are parameters of type uint32_t.
 
 =back
 
@@ -73,35 +65,36 @@ The corresponding value strings are expected to be decimal numbers.
 
 A context for scrypt can be obtained by calling:
 
- EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
 
 The output length of an scrypt key derivation is specified via the
-B<keylen> parameter to the L<EVP_KDF_derive(3)> function.
+B<keylen> parameter to the L<EVP_KDF-derive(3)> function.
 
 =head1 EXAMPLES
 
 This example derives a 64-byte long test vector using scrypt with the password
 "password", salt "NaCl" and N = 1024, r = 8, p = 16.
 
+ EVP_KDF *kdf;
  EVP_KDF_CTX *kctx;
  unsigned char out[64];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_PASS, "password", (size_t)8) <= 0) {
-     error("EVP_KDF_CTRL_SET_PASS");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "NaCl", (size_t)4) <= 0) {
-     error("EVP_KDF_CTRL_SET_SALT");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_N, (uint64_t)1024) <= 0) {
-     error("EVP_KDF_CTRL_SET_SCRYPT_N");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_R, (uint32_t)8) <= 0) {
-     error("EVP_KDF_CTRL_SET_SCRYPT_R");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SCRYPT_P, (uint32_t)16) <= 0) {
-     error("EVP_KDF_CTRL_SET_SCRYPT_P");
+ OSSL_PARAM params[6], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "ID-SCRYPT", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
+                                          "password", (size_t)8);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+                                          "NaCl", (size_t)4);
+ *p++ = OSSL_PARAM_construct_uint64(OSSL_KDF_PARAM_SCRYPT_N, (uint64_t)1024);
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_R, (uint32_t)8);
+ *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_SCRYPT_P, (uint32_t)16);
+ *p = OSSL_PARAM_construct_end();
+ if (EVP_KDF_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
  }
  if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
      error("EVP_KDF_derive");
@@ -130,12 +123,12 @@ RFC 7914
 
 =head1 SEE ALSO
 
-L<EVP_KDF_CTX>,
-L<EVP_KDF_CTX_new_id(3)>,
-L<EVP_KDF_CTX_free(3)>,
-L<EVP_KDF_ctrl(3)>,
-L<EVP_KDF_derive(3)>,
-L<EVP_KDF_CTX(3)/CONTROLS>
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF-CTX(3)/PARAMETERS>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/EVP_KDF-SS.pod b/doc/man7/EVP_KDF-SS.pod
new file mode 100644
index 0000000000..be69606701
--- /dev/null
+++ b/doc/man7/EVP_KDF-SS.pod
@@ -0,0 +1,197 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF-SS - The Single Step / One Step EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF-SS algorithm implements the Single Step key derivation function (SSKDF).
+SSKDF derives a key using input such as a shared secret key (that was generated
+during the execution of a key establishment scheme) and fixedinfo.
+SSKDF is also informally referred to as 'Concat KDF'.
+
+=head2 Auxiliary function
+
+The implementation uses a selectable auxiliary function H, which can be one of:
+
+=over 4
+
+=item B<H(x) = hash(x, digest=md)>
+
+=item B<H(x) = HMAC_hash(x, key=salt, digest=md)>
+
+=item B<H(x) = KMACxxx(x, key=salt, custom="KDF", outlen=mac_size)>
+
+=back
+
+Both the HMAC and KMAC implementations set the key using the 'salt' value.
+The hash and HMAC also require the digest to be set.
+
+=head2 Identity
+
+"SSKDF" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
+
+=head2 Supported parameters
+
+The supported parameters are:
+
+=over 4
+
+=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_MAC> ("mac") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_MAC_SIZE> ("maclen") <size_t>
+
+=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
+
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
+
+=item B<EVP_KDF_CTRL_SET_KEY> ("key") <octet string>
+
+This parameter set the shared secret that is used for key derivation.
+
+=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
+
+This parameter sets an optional value for fixedinfo, also known as otherinfo.
+
+=back
+
+=head1 NOTES
+
+A context for SSKDF can be obtained by calling:
+
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
+
+The output length of an SSKDF is specified via the C<keylen>
+parameter to the L<EVP_KDF-derive(3)> function.
+
+=head1 EXAMPLES
+
+This example derives 10 bytes using H(x) = SHA-256, with the secret key "secret"
+and fixedinfo value "label":
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[4], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *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_end();
+ if (EVP_KDF_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+This example derives 10 bytes using H(x) = HMAC(SHA-256), with the secret key "secret",
+fixedinfo value "label" and salt "salt":
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[6], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
+                                         SN_hmac, strlen(SN_hmac));
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_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_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+This example derives 10 bytes using H(x) = KMAC128(x,salt,outlen), with the secret key "secret"
+fixedinfo value "label", salt of "salt" and KMAC outlen of 20:
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[7], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "SSKDF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_MAC,
+                                         SN_kmac128, strlen(SN_kmac128));
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *p++ = OSSL_PARAM_construct_octet_string(EVP_KDF_CTRL_SET_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_size_t(OSSL_KDF_PARAM_MAC_SIZE, (size_t)20);
+ *p = OSSL_PARAM_construct_end();
+ if (EVP_KDF_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+NIST SP800-56Cr1.
+
+=head1 SEE ALSO
+
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-size(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF(3)/PARAMETERS>
+
+=head1 HISTORY
+
+This functionality was added to OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 2019 The OpenSSL Project Authors. All Rights Reserved.  Copyright
+(c) 2019, Oracle and/or its affiliates.  All rights reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KDF_SSHKDF.pod b/doc/man7/EVP_KDF-SSHKDF.pod
index 04a646c866..0ed57626ef 100644
--- a/doc/man7/EVP_KDF_SSHKDF.pod
+++ b/doc/man7/EVP_KDF-SSHKDF.pod
@@ -2,69 +2,49 @@
 
 =head1 NAME
 
-EVP_KDF_SSHKDF - The SSHKDF EVP_KDF implementation
+EVP_KDF-SSHKDF - The SSHKDF EVP_KDF implementation
 
 =head1 DESCRIPTION
 
 Support for computing the B<SSHKDF> KDF through the B<EVP_KDF> API.
 
-The EVP_KDF_SSHKDF algorithm implements the SSHKDF key derivation function.
+The EVP_KDF-SSHKDF algorithm implements the SSHKDF key derivation function.
 It is defined in RFC 4253, section 7.2 and is used by SSH to derive IVs,
 encryption keys and integrity keys.
 Five inputs are required to perform key derivation: The hashing function
 (for example SHA256), the Initial Key, the Exchange Hash, the Session ID,
 and the derivation key type.
 
-=head2 Numeric identity
+=head2 Identity
 
-B<EVP_KDF_SSHKDF> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
+"SSHKDF" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
 
-=head2 Supported controls
+=head2 Supported parameters
 
-The supported controls are:
+The supported parameters are:
 
 =over 4
 
-=item B<EVP_KDF_CTRL_SET_MD>
+=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
 
-=item B<EVP_KDF_CTRL_SET_KEY>
+=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
 
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
+=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
 
-=item B<EVP_KDF_CTRL_SET_SSHKDF_XCGHASH>
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
 
-=item B<EVP_KDF_CTRL_SET_SSHKDF_SESSION_ID>
+=item B<OSSL_KDF_PARAM_SSHKDF_XCGHASH> ("xcghash") <octet string>
 
-These controls expect two arguments: C<unsigned char *buffer>, C<size_t length>
+=item B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID> ("session_id") <octet string>
 
-They set the respective values to the first B<length> bytes of the buffer
-B<buffer>. If a value is already set, the contents are replaced.
+These parameters set the respective values for the KDF.
+If a value is already set, the contents are replaced.
 
-EVP_KDF_ctrl_str() takes two type strings for these controls:
+=item B<OSSL_KDF_PARAM_SSHKDF_TYPE> ("type") <int>
 
-=over 4
-
-=item "xcghash"
-
-=item "session_id"
-
-The value string is used as is.
-
-=item "hexxcghash"
-
-=item "hexsession_id"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before being passed on as the control value.
-
-=back
-
-=item B<EVP_KDF_CTRL_SET_SSHKDF_TYPE>
-
-This control expects one argument: C<int mode>
-
-Sets the type for the SSHHKDF operation. There are six supported types:
+This parameter sets the type for the SSHHKDF operation.
+There are six supported types:
 
 =over 4
 
@@ -100,50 +80,54 @@ A single char of value 70 (ASCII char 'F').
 
 =back
 
-EVP_KDF_ctrl_str() type string: "type"
-
-The value is a string of length one character. The only valid values
-are the numerical values of the ASCII characters: "A" (65) to "F" (70).
-
 =back
 
 =head1 NOTES
 
 A context for SSHKDF can be obtained by calling:
 
- EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF);
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
 
 The output length of the SSHKDF derivation is specified via the C<keylen>
-parameter to the L<EVP_KDF_derive(3)> function.
-Since the SSHKDF output length is variable, calling L<EVP_KDF_size()>
+parameter to the L<EVP_KDF-derive(3)> function.
+Since the SSHKDF output length is variable, calling L<EVP_KDF-size()>
 to obtain the requisite length is not meaningful. The caller must
 allocate a buffer of the desired length, and pass that buffer to the
-L<EVP_KDF_derive(3)> function along with the desired length.
+L<EVP_KDF-derive(3)> function along with the desired length.
 
 =head1 EXAMPLES
 
 This example derives an 8 byte IV using SHA-256 with a 1K "key" and appropriate
 "xcghash" and "session_id" values:
 
+ EVP_KDF *kdf;
  EVP_KDF_CTX *kctx;
  unsigned char key[1024] = "01234...";
  unsigned char xcghash[32] = "012345...";
  unsigned char session_id[32] = "012345...";
  unsigned char out[8];
  size_t outlen = sizeof(out);
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_SSHKDF);
-
- if (EVP_KDF_CTX_set_md(kctx, EVP_sha256()) <= 0)
-     /* Error */
- if (EVP_KDF_CTX_set1_key(kctx, key, 1024) <= 0)
-     /* Error */
- if (EVP_KDF_CTX_set1_sshkdf_xcghash(kctx, xcghash, 32) <= 0)
-     /* Error */
- if (EVP_KDF_CTX_set1_sshkdf_session_id(kctx, session_id, 32) <= 0)
-     /* Error */
- if (EVP_KDF_CTX_set_sshkdf_type(kctx,
-                    EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV) <= 0)
+ OSSL_PARAM params[6], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "SSHKDF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_KEY,
+                                          key, (size_t)1024);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SSHKDF_XCGHASH,
+                                          xcghash, (size_t)32);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
+                                          session_id, (size_t)32);
+ *p++ = OSSL_PARAM_construct_int(OSSL_KDF_PARAM_SSHKDF_TYPE,
+                                 EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV);
+ *p = OSSL_PARAM_construct_end();
+ if (EVP_KDF_set_params(kctx, params) <= 0)
      /* Error */
+
  if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
      /* Error */
 
@@ -154,13 +138,13 @@ RFC 4253
 
 =head1 SEE ALSO
 
-L<EVP_KDF_CTX>,
-L<EVP_KDF_CTX_new_id(3)>,
-L<EVP_KDF_CTX_free(3)>,
-L<EVP_KDF_ctrl(3)>,
-L<EVP_KDF_size(3)>,
-L<EVP_KDF_derive(3)>,
-L<EVP_KDF_CTX(3)/CONTROLS>
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-size(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF(3)/PARAMETERS>
 
 =head1 COPYRIGHT
 
diff --git a/doc/man7/EVP_KDF-TLS1_PRF.pod b/doc/man7/EVP_KDF-TLS1_PRF.pod
new file mode 100644
index 0000000000..a04f811792
--- /dev/null
+++ b/doc/man7/EVP_KDF-TLS1_PRF.pod
@@ -0,0 +1,113 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF-TLS1_PRF - The TLS1 PRF EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+Support for computing the B<TLS1> PRF through the B<EVP_KDF> API.
+
+The EVP_KDF-TLS1_PRF algorithm implements the PRF used by TLS versions up to
+and including TLS 1.2.
+
+=head2 Identity
+
+"TLS1-PRF" is the name for this implementation; it
+can be used with the EVP_KDF_fetch() function.
+
+=head2 Supported parameters
+
+The supported parameters are:
+
+=over 4
+
+=item B<OSSL_KDF_PARAM_PROPERTIES> ("properties") <UTF8 string>
+
+=item B<OSSL_KDF_PARAM_DIGEST> ("digest") <UTF8 string>
+
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
+
+The C<OSSL_KDF_PARAM_DIGEST> parameter is used to set the message digest
+associated with the TLS PRF.
+EVP_md5_sha1() is treated as a special case which uses the
+PRF algorithm using both B<MD5> and B<SHA1> as used in TLS 1.0 and 1.1.
+
+=item B<OSSL_KDF_PARAM_SECRET> ("secret") <octet string>
+
+This parameter sets the secret value of the TLS PRF.
+Any existing secret value is replaced.
+
+=item B<OSSL_KDF_PARAM_SEED> ("seed") <octet string>
+
+This parameter sets the context seed.
+The length of the context seed cannot exceed 1024 bytes;
+this should be more than enough for any normal use of the TLS PRF.
+
+=back
+
+=head1 NOTES
+
+A context for the TLS PRF can be obtained by calling:
+
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
+
+The digest, secret value and seed must be set before a key is derived otherwise
+an error will occur.
+
+The output length of the PRF is specified by the C<keylen> parameter to the
+EVP_KDF_derive() function.
+
+=head1 EXAMPLES
+
+This example derives 10 bytes using SHA-256 with the secret key "secret"
+and seed value "seed":
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[4], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "TLS1-PRF", NULL);
+ kctx = EVP_KDF_CTX_new(kdf);
+ EVP_KDF_free(kdf);
+
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_DIGEST,
+                                         SN_sha256, strlen(SN_sha256));
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SECRET,
+                                          "secret", (size_t)6);
+ *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SEED,
+                                          "seed", (size_t)4);
+ *p = OSSL_PARAM_construct_end();
+ if (EVP_KDF_set_params(kctx, params) <= 0) {
+     error("EVP_KDF_set_params");
+ }
+ if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
+     error("EVP_KDF_derive");
+ }
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 2246, RFC 5246 and NIST SP 800-135 r1
+
+=head1 SEE ALSO
+
+L<EVP_KDF>,
+L<EVP_KDF-CTX_new_id(3)>,
+L<EVP_KDF-CTX_free(3)>,
+L<EVP_KDF-ctrl(3)>,
+L<EVP_KDF-derive(3)>,
+L<EVP_KDF-CTX(3)/PARAMETERS>
+
+=head1 COPYRIGHT
+
+Copyright 2018-2019 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the Apache License 2.0 (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
diff --git a/doc/man7/EVP_KDF-X942.pod b/doc/man7/EVP_KDF-X942.pod
new file mode 100644
index 0000000000..0b02f2d403
--- /dev/null
+++ b/doc/man7/EVP_KDF-X942.pod
@@ -0,0 +1,122 @@
+=pod
+
+=head1 NAME
+
+EVP_KDF-X942 - The X9.42-2001 asn1 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF-X942 algorith