BCryptKeyDerivation function

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 WINAPI BCryptKeyDerivation(
  _In_     BCRYPT_KEY_HANDLE hKey,
  _In_opt_ BCryptBufferDesc  *pParameterList,
  _Out_    PUCHAR            pbDerivedKey,
  _In_     ULONG             cbDerivedKey,
  _Out_    ULONG             *pcbResult,
  _In_     ULONG             dwFlags
);

Parameters

hKey [in]

Handle of the input key.

pParameterList [in, optional]

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

pbDerivedKey [out]

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

cbDerivedKey [in]

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

pcbResult [out]

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

dwFlags [in]

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). For more information, see WDK and Developer Tools.

Windows Server 2008 and Windows Vista:  To call this function in kernel mode, use Ksecdd.lib.

Requirements

See also

BCryptDeriveKey

NCryptKeyDerivation