BCryptKeyDerivation function (bcrypt.h)

The BCryptKeyDerivation function derives a key by invoking a Key Derivation Function (KDF), with all parameters explicitly being provided.

It is similar in functionality to BCryptDeriveKey but directly invokes a KDF algorithm, so does not require a BCRYPT_SECRET_HANDLE value as input.

Syntax

NTSTATUS BCryptKeyDerivation(
  [in]           BCRYPT_KEY_HANDLE hKey,
  [in, optional] BCryptBufferDesc  *pParameterList,
  [out]          PUCHAR            pbDerivedKey,
  [in]           ULONG             cbDerivedKey,
  [out]          ULONG             *pcbResult,
  [in]           ULONG             dwFlags
);

Parameters

[in] hKey

Handle of the key derivation function (KDF) key. See Remarks.

[in, optional] pParameterList

The address of a BCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and can be NULL if it is not needed.

The parameters can be specific to a key derivation function (KDF) or generic. The following table shows the required and optional parameters for specific KDFs implemented by the Microsoft Primitive provider. Some additional information can be found in the documentation for BCryptBuffer.

For some algorithms, the KDF_GENERIC_PARAMETER can be used instead of specifying several parameters. This maps to KDF specific parameters in the following manner:

SP800-108 HMAC in counter mode:

• KDF_GENERIC_PARAMETER = KDF_LABEL || 0x00 || KDF_CONTEXT

SP800-56A:

• KDF_GENERIC_PARAMETER = KDF_ALGORITHMID || KDF_PARTYUINFO || KDF_PARTYVINFO {|| KDF_SUPPPUBINFO } {|| KDF_SUPPPRIVINFO }

PBKDF2:

• KDF_GENERIC_PARAMETER = KDF_SALT

[out] pbDerivedKey

Address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer.

[in] cbDerivedKey

Size, in bytes, of the buffer pointed to by the pbDerivedKey parameter.

[out] pcbResult

Pointer to a ULONG that receives the number of bytes that were copied to the buffer pointed to by the pbDerivedKey parameter.

[in] dwFlags

Flags that modify the behavior of this function. The following value can be used with the Microsoft Primitive provider.

Return value

Returns a status code that indicates the success or failure of the function.

Remarks

The flow for using BCryptKeyDerivation is to:

1. Determine the KDF algorithm you are going to use and get a algorithm handle for it. You can use the following algorithm identifiers in the BCryptOpenAlgorithmProvider:

• BCRYPT_CAPI_KDF_ALGORITHM
• BCRYPT_SP800108_CTR_HMAC_ALGORITHM
• BCRYPT_SP80056A_CONCAT_ALGORITHM
• BCRYPT_PBKDF2_ALGORITHM
• BCRYPT_TLS1_1_KDF_ALGORITHM
• BCRYPT_TLS1_2_KDF_ALGORITHM
• BCRYPT_HKDF_ALGORITHM

2. Determine the secret data from which you are going to derive a key, and supply it to BCryptGenerateSymmetricKey with the algorithm handle, to produce a KDF key handle.

3. Call BCryptKeyDerivation with the KDF key handle.

To call this function in kernel mode, use Cng.lib, which is part of the Driver Development Kit (DDK). Windows Server 2008 and Windows Vista: To call this function in kernel mode, use Ksecdd.lib.

HKDF

In HKDF, a distinction is made between deriving a key from either:

1. The output of a secret agreement function, which is not uniformly random, and is considered to be input keying material (IKM).
2. A uniformly random secret value.

The first step is to "Extract" a pseudorandom key (PRK) from the provided secret data.

This step is performed by calling BCryptSetProperty on the KDF key handle with BCRYPT_HKDF_HASH_ALGORITHM to set the hash algorithm to use in HMAC computations in HKDF. This is followed by a second call to BCryptSetProperty with one of either:

1. If the provided secret data represents IKM, use BCRYPT_HKDF_SALT_AND_FINALIZE to provide the optional salt value and extract the PRK from the IKM and finalize the KDF key handle.
2. Otherwise, use BCRYPT_HKDF_PRK_AND_FINALIZE to directly transform the provided secret into the HKDF PRK and finalize the KDF key handle.

The second step is to "Expand" the PRK into an output derived key.

This step is performed by calling BCryptKeyDerivation on a finalized KDF key handle.

Requirements

See also

BCryptDeriveKey

BCryptBufferDesc

BCryptBuffer

NCryptKeyDerivation