BCryptKeyDerivation function (bcrypt.h)

Article
02/22/2024

The BCryptKeyDerivation function derives a key without requiring a secret agreement. It is similar in functionality to BCryptDeriveKey but 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 input key.

[in, optional] pParameterList

Pointer to 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.

KDF	Parameter	Required
SP800-108 HMAC in counter mode	KDF_LABEL	yes
	KDF_CONTEXT	yes
	KDF_HASH_ALGORITHM	yes
SP800-56A	KDF_ALGORITHMID	yes
	KDF_PARTYUINFO	yes
	KDF_PARTYVINFO	yes
	KDF_HASH_ALGORITHM	yes
	KDF_SUPPPUBINFO	no
	KDF_SUPPPRIVINFO	no
PBKDF2	KDF_HASH_ALGORITHM	yes
	KDF_SALT	yes
	KDF_ITERATION_COUNT	no
CAPI_KDF	KDF_HASH_ALGORITHM	yes

The following generic parameter can be used:

KDF_GENERIC_PARAMETER

Generic parameters map 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
KDF_ITERATION_COUNT – defaults to 10000

CAPI_KDF

KDF_GENERIC_PARAMETER = Not Used

[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 variable 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.

Value	Meaning
BCRYPT_CAPI_AES_FLAG	Specifies that the target algorithm is AES and that the key therefore must be double expanded. This flag is only valid with the CAPI_KDF algorithm.

Return value

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

Remarks

You can use the following algorithm identifiers in the BCryptOpenAlgorithmProvider function before calling BCryptKeyDerivation:

BCRYPT_CAPI_KDF_ALGORITHM
BCRYPT_SP800108_CTR_HMAC_ALGORITHM
BCRYPT_SP80056A_CONCAT_ALGORITHM
BCRYPT_PBKDF2_ALGORITHM

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.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps \| UWP apps]
Minimum supported server	Windows Server 2012 [desktop apps \| UWP apps]
Target Platform	Windows
Header	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll