EVP_KDF-TLS13_KDF.7ossl - Man Page

The TLS 1.3 EVP_KDF implementation

Description

Support for computing the TLS 1.3 version of the HKDF KDF through the EVP_KDF API.

The EVP_KDF-TLS13_KDF algorithm implements the HKDF key derivation function as used by TLS 1.3.

The output is considered to be keying material.

Identity

"TLS13-KDF" is the name for this implementation; it can be used with the EVP_KDF_fetch() function.

Supported parameters

The supported parameters are:

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>
"digest" (OSSL_KDF_PARAM_DIGEST) <UTF8 string>
"key" (OSSL_KDF_PARAM_KEY) <octet string>
"salt" (OSSL_KDF_PARAM_SALT) <octet string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3).

"prefix" (OSSL_KDF_PARAM_PREFIX) <octet string>

This parameter sets the label prefix on the specified TLS 1.3 KDF context. For TLS 1.3 this should be set to the ASCII string "tls13 " without a trailing zero byte.  Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"label" (OSSL_KDF_PARAM_LABEL) <octet string>

This parameter sets the label on the specified TLS 1.3 KDF context. Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"data" (OSSL_KDF_PARAM_DATA) <octet string>

This parameter sets the context data on the specified TLS 1.3 KDF context. Refer to RFC 8446 section 7.1 "Key Schedule" for details.

"mode" (OSSL_KDF_PARAM_MODE) <UTF8 string> or <integer>

This parameter sets the mode for the TLS 1.3 KDF operation. There are two modes that are currently defined:

"EXTRACT_ONLY" or EVP_KDF_HKDF_MODE_EXTRACT_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the extract operation. The value returned will be the intermediate fixed-length pseudorandom key K.  The keylen parameter must match the size of K, which can be looked up by calling EVP_KDF_CTX_get_kdf_size() after setting the mode and digest.

The digest, key and salt values must be set before a key is derived otherwise an error will occur.

"EXPAND_ONLY" or EVP_KDF_HKDF_MODE_EXPAND_ONLY

In this mode calling EVP_KDF_derive(3) will just perform the expand operation. The input key should be set to the intermediate fixed-length pseudorandom key K returned from a previous extract operation.

The digest, key and info values must be set before a key is derived otherwise an error will occur.

The OpenSSL FIPS provider also supports the following parameters:

"fips-indicator" (OSSL_KDF_PARAM_FIPS_APPROVED_INDICATOR) <integer>

A getter that returns 1 if the operation is FIPS approved, or 0 otherwise. This may be used after calling EVP_KDF_derive. It returns 0 if any "***-check" related parameter is set to 0 and the check fails.

"digest-check" (OSSL_KDF_PARAM_FIPS_DIGEST_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if used digest is not approved. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

According to RFC 8446, the following are approved digest algorithms: SHA2-256, SHA2-384.

"key-check" (OSSL_KDF_PARAM_FIPS_KEY_CHECK) <integer>

The default value of 1 causes an error during EVP_KDF_CTX_set_params() if the length of used key-derivation key (OSSL_KDF_PARAM_KEY) is shorter than 112 bits. Setting this to zero will ignore the error and set the approved "fips-indicator" to 0. This option breaks FIPS compliance if it causes the approved "fips-indicator" to return 0.

Notes

This KDF is intended for use by the TLS 1.3 implementation in libssl. It does not support all the options and capabilities that HKDF does.

The OSSL_PARAM array passed to EVP_KDF_derive(3) or EVP_KDF_CTX_set_params(3) must specify all of the parameters required. This KDF does not support a piecemeal approach to providing these.

A context for a TLS 1.3 KDF can be obtained by calling:

 EVP_KDF *kdf = EVP_KDF_fetch(NULL, "TLS13-KDF", NULL);
 EVP_KDF_CTX *kctx = EVP_KDF_CTX_new(kdf);

The output length of a TLS 1.3 KDF expand operation is specified via the keylen parameter to the EVP_KDF_derive(3) function.  When using EVP_KDF_HKDF_MODE_EXTRACT_ONLY the 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_CTX_get_kdf_size() after setting the mode and digest on the EVP_KDF_CTX.

Conforming to

RFC 8446

See Also

EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_get_kdf_size(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3), EVP_KDF-HKDF(7)

History

This functionality was added in OpenSSL 3.0.

Referenced By

EVP_KDF-HKDF.7ossl(7), OSSL_PROVIDER-default.7ossl(7), OSSL_PROVIDER-FIPS.7ossl(7).

2025-04-15 3.5.0 OpenSSL