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

Parameters

hKey

Handle of the input key.

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

pbDerivedKey

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

cbDerivedKey

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

pcbResult

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

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). 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

   
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

See Also

BCryptDeriveKey

NCryptKeyDerivation