BCryptKeyDerivation

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(
         BCRYPT_KEY_HANDLE hKey,
         BCryptBufferDesc *pParameterList,
         PUCHAR pbDerivedKey,
         ULONG cbDerivedKey,
         ULONG *pcbResult,
         ULONG dwFlags
)

Parameters

hKey
Type: BCRYPT_KEY_HANDLE

[in] Handle of the input key.

pParameterList
Type: BCryptBufferDesc *

[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
Type: PUCHAR

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

cbDerivedKey
Type: ULONG

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

pcbResult
Type: ULONG *

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

dwFlags
Type: ULONG

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

Return value

Type: NTSTATUS

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

Requirements

Header: Declared in bcrypt.h.

Library: Use bcrypt.lib.