--- /dev/null
+=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
--- /dev/null
+=pod
+
+=head1 NAME
+
+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
+derivation function, as described in SP800-132; it derives a key from a password
+using a salt and iteration count.
+
+=head2 Identity
+
+"PBKDF2" 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_PASSWORD> ("pass") <octet string>
+
+=item B<OSSL_KDF_PARAM_SALT> ("salt") <octet string>
+
+=item B<OSSL_KDF_PARAM_ITER> ("iter") <unsigned int>
+
+This parameter has a default value of 2048.
+
+=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>.
+
+=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:
+
+=over 4
+
+=item - the iteration count is at least 1000.
+
+=item - the salt length is at least 128 bits.
+
+=item - the derived key length is at least 112 bits.
+
+=back
+
+The default provider uses a default mode of 1 for backwards compatibility,
+and the fips provider uses a default mode of 0.
+
+The value string is expected to be a decimal number 0 or 1.
+
+=back
+
+=head1 NOTES
+
+A typical application of this algorithm is to derive keying material for an
+encryption algorithm from a password in the B<pass>, a salt in B<salt>,
+and an iteration count.
+
+Increasing the B<iter> parameter slows down the algorithm which makes it
+harder for an attacker to perform a brute force attack using a large number
+of candidate passwords.
+
+No assumption is made regarding the given password; it is simply treated as a
+byte sequence.
+
+=head1 CONFORMING TO
+
+SP800-132
+
+=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 HISTORY
+
+This functionality was added to OpenSSL 3.0.
+
+=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
--- /dev/null
+=pod
+
+=head1 NAME
+
+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
+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
+systems that lack large amounts of main memory (such as GPUs or ASICs)
+computationally infeasible.
+
+scrypt provides three work factors that can be customized: N, r and p. N, which
+has to be a positive power of two, is the general work factor and scales CPU
+time in an approximately linear fashion. r is the block size of the internally
+used hash function and p is the parallelization factor. Both r and p need to be
+greater than zero. The amount of RAM that scrypt requires for its computation
+is roughly (128 * N * r * p) bytes.
+
+In the original paper of Colin Percival ("Stronger Key Derivation via
+Sequential Memory-Hard Functions", 2009), the suggested values that give a
+computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
+2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
+this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
+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 Identity
+
+"ID-SCRYPT" 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_PASSWORD> ("pass") <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_SCRYPT_N> ("n") <int>
+
+=item B<OSSL_KDF_PARAM_SCRYPT_R> ("r") <int>
+
+=item B<OSSL_KDF_PARAM_SCRYPT_P> ("p") <int>
+
+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
+
+=head1 NOTES
+
+A context for scrypt can be obtained by calling:
+
+ 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.
+
+=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];
+ 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");
+ }
+
+ {
+ const unsigned char expected[sizeof(out)] = {
+ 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
+ 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
+ 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
+ 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
+ 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
+ 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
+ 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
+ 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
+ };
+
+ assert(!memcmp(out, expected, sizeof(out)));
+ }
+
+ EVP_KDF_CTX_free(kctx);
+
+=head1 CONFORMING TO
+
+RFC 7914
+
+=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 2017-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
--- /dev/null
+=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
--- /dev/null
+=pod
+
+=head1 NAME
+
+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.
+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 Identity
+
+"SSHKDF" 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>
+
+These parameters work as described in L<EVP_KDF(3)/PARAMETERS>.
+
+=item B<OSSL_KDF_PARAM_SSHKDF_XCGHASH> ("xcghash") <octet string>
+
+=item B<OSSL_KDF_PARAM_SSHKDF_SESSION_ID> ("session_id") <octet string>
+
+These parameters set the respective values for the KDF.
+If a value is already set, the contents are replaced.
+
+=item B<OSSL_KDF_PARAM_SSHKDF_TYPE> ("type") <int>
+
+This parameter sets the type for the SSHHKDF operation.
+There are six supported types:
+
+=over 4
+
+=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
+
+The Initial IV from client to server.
+A single char of value 65 (ASCII char 'A').
+
+=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
+
+The Initial IV from server to client
+A single char of value 66 (ASCII char 'B').
+
+=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
+
+The Encryption Key from client to server
+A single char of value 67 (ASCII char 'C').
+
+=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
+
+The Encryption Key from server to client
+A single char of value 68 (ASCII char 'D').
+
+=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
+
+The Integrity Key from client to server
+A single char of value 69 (ASCII char 'E').
+
+=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
+
+The Integrity Key from client to server
+A single char of value 70 (ASCII char 'F').
+
+=back
+
+=back
+
+=head1 NOTES
+
+A context for SSHKDF can be obtained by calling:
+
+ 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()>
+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.
+
+=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);
+ 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 */
+
+
+=head1 CONFORMING TO
+
+RFC 4253
+
+=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 COPYRIGHT
+
+Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (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
+
--- /dev/null
+=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
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_KDF-X942 - The X9.42-2001 asn1 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF-X942 algorithm implements the key derivation function (X942KDF).
+X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
+derive a key using input such as a shared secret key and other info. The other
+info is DER encoded data that contains a 32 bit counter.
+
+=head2 Identity
+
+"X942KDF" 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>.
+
+=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
+
+The shared secret used for key derivation. This parameter sets the secret.
+
+=item B<OSSL_KDF_PARAM_UKM> ("ukm") <octet string>
+
+This parameter is an optional random string that is provided
+by the sender called "partyAInfo".
+In CMS this is the user keying material.
+
+=item B<OSSL_KDF_PARAM_CEK_ALG> ("cekalg") <UTF8 string>
+
+This parameter sets the CEK wrapping algorithm name.
+
+=back
+
+=head1 NOTES
+
+A context for X942KDF can be obtained by calling:
+
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
+
+The output length of an X942KDF is specified via the C<keylen>
+parameter to the L<EVP_KDF-derive(3)> function.
+
+=head1 EXAMPLES
+
+This example derives 24 bytes, with the secret key "secret" and a random user
+keying material:
+
+ EVP_KDF_CTX *kctx;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[192/8];
+ unsignred char ukm[64];
+ OSSL_PARAM params[5], *p = params;
+
+ if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
+ error("RAND_bytes");
+
+ kdf = EVP_KDF_fetch(NULL, "X942KDF", NULL);
+ if (kctx == NULL)
+ error("EVP_KDF_fetch");
+ kctx = EVP_KDF_CTX_new(kdf);
+ if (kctx == NULL)
+ error("EVP_KDF_CTX_new");
+ 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_UKM, ukm, sizeof(ukm));
+ *p++ = OSSL_PARAM_construct_utf8_string(OSSL_KDF_PARAM_CEK_ALG,
+ SN_id_smime_alg_CMS3DESwrap,
+ strlen(SN_id_smime_alg_CMS3DESwrap));
+ *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 2631
+
+=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.
+
+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
--- /dev/null
+=pod
+
+=head1 NAME
+
+EVP_KDF-X963 - The X9.63-2001 EVP_KDF implementation
+
+=head1 DESCRIPTION
+
+The EVP_KDF-X963 algorithm implements the key derivation function (X963KDF).
+X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to
+derive a key using input such as a shared secret key and shared info.
+
+=head2 Identity
+
+"X963KDF" 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>.
+
+=item B<OSSL_KDF_PARAM_KEY> ("key") <octet string>
+
+The shared secret used for key derivation.
+This parameter sets the secret.
+
+=item B<OSSL_KDF_PARAM_INFO> ("info") <octet string>
+
+This parameter specifies an optional value for shared info.
+
+=back
+
+=head1 NOTES
+
+X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
+X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
+
+A context for X963KDF can be obtained by calling:
+
+ EVP_KDF *kdf = EVP_KDF_fetch(NULL, "X963KDF", NULL);
+ EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);
+
+The output length of an X963KDF is specified via the C<keylen>
+parameter to the L<EVP_KDF-derive(3)> function.
+
+=head1 EXAMPLES
+
+This example derives 10 bytes, with the secret key "secret" and sharedinfo
+value "label":
+
+ EVP_KDF *kdf;
+ EVP_KDF_CTX *kctx;
+ unsigned char out[10];
+ OSSL_PARAM params[4], *p = params;
+
+ kdf = EVP_KDF_fetch(NULL, "X963KDF", 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_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);
+
+=head1 CONFORMING TO
+
+"SEC 1: Elliptic Curve Cryptography"
+
+=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 HISTORY
+
+This functionality was added to OpenSSL 3.0.
+
+=head1 COPYRIGHT
+
+Copyright 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
+++ /dev/null
-=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 Numeric identity
-
-B<EVP_KDF_HKDF> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_SALT>
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-=item B<EVP_KDF_CTRL_SET_KEY>
-
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_RESET_HKDF_INFO>
-
-This control does not expect any arguments.
-
-Resets the context info buffer to zero length.
-
-=item B<EVP_KDF_CTRL_ADD_HKDF_INFO>
-
-This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
-
-Sets the info value to the first B<infolen> bytes of the buffer B<info>. If a
-value is already set, the contents of the buffer are appended to the existing
-value.
-
-The total length of the context info buffer cannot exceed 1024 bytes;
-this should be more than enough for any normal use of HKDF.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "info"
-
-The value string is used as is.
-
-=item "hexinfo"
-
-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_HKDF_MODE>
-
-This control expects one argument: C<int mode>
-
-Sets the mode for the HKDF operation. There are three modes that are currently
-defined:
-
-=over 4
-
-=item EVP_KDF_HKDF_MODE_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 EVP_KDF_HKDF_MODE_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 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.
-
-=back
-
-EVP_KDF_ctrl_str() type string: "mode"
-
-The value string is expected to be one of: "EXTRACT_AND_EXPAND", "EXTRACT_ONLY"
-or "EXPAND_ONLY".
-
-=back
-
-=head1 NOTES
-
-A context for HKDF can be obtained by calling:
-
- EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
-
-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_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_HKDF);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
- error("EVP_KDF_CTRL_SET_SALT");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_KEY");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_HKDF_INFO, "label", (size_t)5) <= 0) {
- error("EVP_KDF_CTRL_ADD_HKDF_INFO");
- }
- 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_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>
-
-=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
+++ /dev/null
-=pod
-
-=head1 NAME
-
-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
-derivation function, as described in SP800-132; it derives a key from a password
-using a salt and iteration count.
-
-=head2 Numeric identity
-
-B<EVP_KDF_PBKDF2> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_PASS>
-
-=item B<EVP_KDF_CTRL_SET_SALT>
-
-=item B<EVP_KDF_CTRL_SET_ITER>
-
-This control has a default value of 2048.
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_PBKDF2_PKCS5_MODE>
-
-This control expects one argument: C<int mode>
-
-This control can be used to enable or disable SP800-132 compliance checks.
-
-Setting the mode to 0 enables the compliance checks.
-
-The checks performed are:
-
-=over 4
-
-=item - the iteration count is at least 1000.
-
-=item - the salt length is at least 128 bits.
-
-=item - the derived key length is at least 112 bits.
-
-=back
-
-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
-
-=head1 NOTES
-
-A typical application of this algorithm is to derive keying material for an
-encryption algorithm from a password in the B<pass>, a salt in B<salt>,
-and an iteration count.
-
-Increasing the B<iter> parameter slows down the algorithm which makes it
-harder for an attacker to perform a brute force attack using a large number
-of candidate passwords.
-
-No assumption is made regarding the given password; it is simply treated as a
-byte sequence.
-
-=head1 CONFORMING TO
-
-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>
-
-=head1 HISTORY
-
-This functionality was added to OpenSSL 3.0.
-
-=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
+++ /dev/null
-=pod
-
-=head1 NAME
-
-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
-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
-systems that lack large amounts of main memory (such as GPUs or ASICs)
-computationally infeasible.
-
-scrypt provides three work factors that can be customized: N, r and p. N, which
-has to be a positive power of two, is the general work factor and scales CPU
-time in an approximately linear fashion. r is the block size of the internally
-used hash function and p is the parallelization factor. Both r and p need to be
-greater than zero. The amount of RAM that scrypt requires for its computation
-is roughly (128 * N * r * p) bytes.
-
-In the original paper of Colin Percival ("Stronger Key Derivation via
-Sequential Memory-Hard Functions", 2009), the suggested values that give a
-computation time of less than 5 seconds on a 2.5 GHz Intel Core 2 Duo are N =
-2^20 = 1048576, r = 8, p = 1. Consequently, the required amount of memory for
-this computation is roughly 1 GiB. On a more recent CPU (Intel i7-5930K at 3.5
-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
-
-B<EVP_KDF_SCRYPT> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_PASS>
-
-=item B<EVP_KDF_CTRL_SET_SALT>
-
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_SCRYPT_N>
-
-=item B<EVP_KDF_CTRL_SET_SCRYPT_R>
-
-=item B<EVP_KDF_CTRL_SET_SCRYPT_P>
-
-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.
-
-=back
-
-=head1 NOTES
-
-A context for scrypt can be obtained by calling:
-
- EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SCRYPT);
-
-The output length of an scrypt key derivation is specified via the
-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_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");
- }
- if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
- error("EVP_KDF_derive");
- }
-
- {
- const unsigned char expected[sizeof(out)] = {
- 0xfd, 0xba, 0xbe, 0x1c, 0x9d, 0x34, 0x72, 0x00,
- 0x78, 0x56, 0xe7, 0x19, 0x0d, 0x01, 0xe9, 0xfe,
- 0x7c, 0x6a, 0xd7, 0xcb, 0xc8, 0x23, 0x78, 0x30,
- 0xe7, 0x73, 0x76, 0x63, 0x4b, 0x37, 0x31, 0x62,
- 0x2e, 0xaf, 0x30, 0xd9, 0x2e, 0x22, 0xa3, 0x88,
- 0x6f, 0xf1, 0x09, 0x27, 0x9d, 0x98, 0x30, 0xda,
- 0xc7, 0x27, 0xaf, 0xb9, 0x4a, 0x83, 0xee, 0x6d,
- 0x83, 0x60, 0xcb, 0xdf, 0xa2, 0xcc, 0x06, 0x40
- };
-
- assert(!memcmp(out, expected, sizeof(out)));
- }
-
- EVP_KDF_CTX_free(kctx);
-
-=head1 CONFORMING TO
-
-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>
-
-=head1 COPYRIGHT
-
-Copyright 2017-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
+++ /dev/null
-=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 Numeric identity
-
-B<EVP_KDF_SS> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-=item B<EVP_KDF_CTRL_SET_MAC>
-
-=item B<EVP_MAC_CTRL_SET_MAC_SIZE>
-
-=item B<EVP_KDF_CTRL_SET_SALT>
-
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_KEY>
-
-This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
-
-The shared secret used for key derivation. This control sets the secret.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "secret"
-
-The value string is used as is.
-
-=item "hexsecret"
-
-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_SSKDF_INFO>
-
-This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
-
-An optional value for fixedinfo, also known as otherinfo. This control sets the fixedinfo.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "info"
-
-The value string is used as is.
-
-=item "hexinfo"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before being passed on as the control value.
-
-=back
-
-=back
-
-=head1 NOTES
-
-A context for SSKDF can be obtained by calling:
-
-EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
-
-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_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_KEY");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
- error("EVP_KDF_CTRL_SET_SSKDF_INFO");
- }
- 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_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("HMAC")) <= 0) {
- error("EVP_KDF_CTRL_SET_MAC");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_KEY");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
- error("EVP_KDF_CTRL_SET_SSKDF_INFO");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
- error("EVP_KDF_CTRL_SET_SALT");
- }
- 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_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_SS);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC, EVP_get_macbyname("KMAC128")) <= 0) {
- error("EVP_KDF_CTRL_SET_MAC");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_KEY");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SSKDF_INFO, "label", (size_t)5) <= 0) {
- error("EVP_KDF_CTRL_SET_SSKDF_INFO");
- }
- /* If not specified the salt will be set to a default value */
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SALT, "salt", (size_t)4) <= 0) {
- error("EVP_KDF_CTRL_SET_SALT");
- }
- /* If not specified the default size will be the size of the derived key */
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MAC_SIZE, (size_t)20) <= 0) {
- error("EVP_KDF_CTRL_SET_MAC_SIZE");
- }
- 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_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>
-
-=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
+++ /dev/null
-=pod
-
-=head1 NAME
-
-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.
-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
-
-B<EVP_KDF_SSHKDF> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-=item B<EVP_KDF_CTRL_SET_KEY>
-
-These controls work as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_SSHKDF_XCGHASH>
-
-=item B<EVP_KDF_CTRL_SET_SSHKDF_SESSION_ID>
-
-These controls expect two arguments: C<unsigned char *buffer>, C<size_t length>
-
-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.
-
-EVP_KDF_ctrl_str() takes two type strings for these controls:
-
-=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:
-
-=over 4
-
-=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_CLI_TO_SRV
-
-The Initial IV from client to server.
-A single char of value 65 (ASCII char 'A').
-
-=item EVP_KDF_SSHKDF_TYPE_INITIAL_IV_SRV_TO_CLI
-
-The Initial IV from server to client
-A single char of value 66 (ASCII char 'B').
-
-=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_CLI_TO_SRV
-
-The Encryption Key from client to server
-A single char of value 67 (ASCII char 'C').
-
-=item EVP_KDF_SSHKDF_TYPE_ENCRYPTION_KEY_SRV_TO_CLI
-
-The Encryption Key from server to client
-A single char of value 68 (ASCII char 'D').
-
-=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_CLI_TO_SRV
-
-The Integrity Key from client to server
-A single char of value 69 (ASCII char 'E').
-
-=item EVP_KDF_SSHKDF_TYPE_INTEGRITY_KEY_SRV_TO_CLI
-
-The Integrity Key from client to server
-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);
-
-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()>
-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.
-
-=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_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)
- /* Error */
- if (EVP_KDF_derive(kctx, out, &outlen) <= 0)
- /* Error */
-
-
-=head1 CONFORMING TO
-
-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>
-
-=head1 COPYRIGHT
-
-Copyright 2016-2018 The OpenSSL Project Authors. All Rights Reserved.
-
-Licensed under the OpenSSL license (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
-
+++ /dev/null
-=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 Numeric identity
-
-B<EVP_KDF_TLS1_PRF> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-The C<EVP_KDF_CTRL_SET_MD> control 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<EVP_KDF_CTRL_SET_TLS_SECRET>
-
-This control expects two arguments: C<unsigned char *sec>, C<size_t seclen>
-
-Sets the secret value of the TLS PRF to B<seclen> bytes of the buffer B<sec>.
-Any existing secret value is replaced.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "secret"
-
-The value string is used as is.
-
-=item "hexsecret"
-
-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_RESET_TLS_SEED>
-
-This control does not expect any arguments.
-
-Resets the context seed buffer to zero length.
-
-=item B<EVP_KDF_CTRL_ADD_TLS_SEED>
-
-This control expects two arguments: C<unsigned char *seed>, C<size_t seedlen>
-
-Sets the seed to B<seedlen> bytes of B<seed>. If a seed is already set it is
-appended to the existing value.
-
-The total length of the context seed buffer cannot exceed 1024 bytes;
-this should be more than enough for any normal use of the TLS PRF.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "seed"
-
-The value string is used as is.
-
-=item "hexseed"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before being passed on as the control value.
-
-=back
-
-=back
-
-=head1 NOTES
-
-A context for the TLS PRF can be obtained by calling:
-
- EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF, NULL);
-
-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_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_TLS1_PRF);
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_TLS_SECRET,
- "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_TLS_SECRET");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_ADD_TLS_SEED, "seed", (size_t)4) <= 0) {
- error("EVP_KDF_CTRL_ADD_TLS_SEED");
- }
- 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_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>
-
-=head1 COPYRIGHT
-
-Copyright 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
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_KDF_X942 - The X9.42-2001 asn1 EVP_KDF implementation
-
-=head1 DESCRIPTION
-
-The EVP_KDF_X942 algorithm implements the key derivation function (X942KDF).
-X942KDF is used by Cryptographic Message Syntax (CMS) for DH KeyAgreement, to
-derive a key using input such as a shared secret key and other info. The other
-info is DER encoded data that contains a 32 bit counter.
-
-=head2 Numeric identity
-
-B<EVP_KDF_X942> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_KEY>
-
-This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
-
-The shared secret used for key derivation. This control sets the secret.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "secret"
-
-The value string is used as is.
-
-=item "hexsecret"
-
-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_UKM>
-
-This control expects two arguments: C<unsigned char *ukm>, C<size_t ukmlen>
-
-An optional random string that is provided by the sender called "partyAInfo".
-In CMS this is the user keying material.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "ukm"
-
-The value string is used as is.
-
-=item "hexukm"
-
-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_CEK_ALG>
-
-This control expects one argument: C<char *alg>
-
-The CEK wrapping algorithm name.
-
-EVP_KDF_ctrl_str() type string: "cekalg"
-
-The value string is used as is.
-
-=back
-
-=head1 NOTES
-
-A context for X942KDF can be obtained by calling:
-
-EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
-
-The output length of an X942KDF is specified via the C<keylen>
-parameter to the L<EVP_KDF_derive(3)> function.
-
-=head1 EXAMPLES
-
-This example derives 24 bytes, with the secret key "secret" and a random user
-keying material:
-
- EVP_KDF_CTX *kctx;
- unsigned char out[192/8];
- unsignred char ukm[64];
-
- if (RAND_bytes(ukm, sizeof(ukm)) <= 0)
- error("RAND_bytes");
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_X942);
- if (kctx == NULL)
- error("EVP_KDF_CTX_new_id");
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0)
- error("EVP_KDF_CTRL_SET_MD");
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0)
- error("EVP_KDF_CTRL_SET_KEY");
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_UKM, ukm, sizeof(ukm)) <= 0)
- error("EVP_KDF_CTRL_SET_UKM");
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_CEK_ALG,
- SN_id_smime_alg_CMS3DESwrap) <= 0)
- error("EVP_KDF_CTRL_SET_CEK_ALG");
- if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0)
- error("EVP_KDF_derive");
-
- EVP_KDF_CTX_free(kctx);
-
-=head1 CONFORMING TO
-
-RFC 2631
-
-=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>
-
-=head1 HISTORY
-
-This functionality was added to OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 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
+++ /dev/null
-=pod
-
-=head1 NAME
-
-EVP_KDF_X963 - The X9.63-2001 EVP_KDF implementation
-
-=head1 DESCRIPTION
-
-The EVP_KDF_X963 algorithm implements the key derivation function (X963KDF).
-X963KDF is used by Cryptographic Message Syntax (CMS) for EC KeyAgreement, to
-derive a key using input such as a shared secret key and shared info.
-
-=head2 Numeric identity
-
-B<EVP_KDF_X963> is the numeric identity for this implementation; it
-can be used with the EVP_KDF_CTX_new_id() function.
-
-=head2 Supported controls
-
-The supported controls are:
-
-=over 4
-
-=item B<EVP_KDF_CTRL_SET_MD>
-
-This control works as described in L<EVP_KDF_CTX(3)/CONTROLS>.
-
-=item B<EVP_KDF_CTRL_SET_KEY>
-
-This control expects two arguments: C<unsigned char *secret>, C<size_t secretlen>
-
-The shared secret used for key derivation. This control sets the secret.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "secret"
-
-The value string is used as is.
-
-=item "hexsecret"
-
-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_SHARED_INFO>
-
-This control expects two arguments: C<unsigned char *info>, C<size_t infolen>
-
-An optional value for shared info. This control sets the shared info.
-
-EVP_KDF_ctrl_str() takes two type strings for this control:
-
-=over 4
-
-=item "info"
-
-The value string is used as is.
-
-=item "hexinfo"
-
-The value string is expected to be a hexadecimal number, which will be
-decoded before being passed on as the control value.
-
-=back
-
-=back
-
-=head1 NOTES
-
-X963KDF is very similar to the SSKDF that uses a digest as the auxiliary function,
-X963KDF appends the counter to the secret, whereas SSKDF prepends the counter.
-
-A context for X963KDF can be obtained by calling:
-
-EVP_KDF_CTX *kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
-
-The output length of an X963KDF is specified via the C<keylen>
-parameter to the L<EVP_KDF_derive(3)> function.
-
-=head1 EXAMPLES
-
-This example derives 10 bytes, with the secret key "secret" and sharedinfo
-value "label":
-
- EVP_KDF_CTX *kctx;
- unsigned char out[10];
-
- kctx = EVP_KDF_CTX_new_id(EVP_KDF_X963);
-
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_MD, EVP_sha256()) <= 0) {
- error("EVP_KDF_CTRL_SET_MD");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_KEY, "secret", (size_t)6) <= 0) {
- error("EVP_KDF_CTRL_SET_KEY");
- }
- if (EVP_KDF_ctrl(kctx, EVP_KDF_CTRL_SET_SHARED_INFO, "label", (size_t)5) <= 0) {
- error("EVP_KDF_CTRL_SET_SHARED_INFO");
- }
- if (EVP_KDF_derive(kctx, out, sizeof(out)) <= 0) {
- error("EVP_KDF_derive");
- }
-
- EVP_KDF_CTX_free(kctx);
-
-=head1 CONFORMING TO
-
-"SEC 1: Elliptic Curve Cryptography"
-
-=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>
-
-=head1 HISTORY
-
-This functionality was added to OpenSSL 3.0.
-
-=head1 COPYRIGHT
-
-Copyright 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
projects / oweals / openssl.git / commitdiff