--- /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
=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:
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 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
=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
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
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");
=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
--- /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
=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
=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 */
=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
--- /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_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_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 / openssl.git / commitdiff