Edit

Share via

BCryptKeyDerivation function (bcrypt.h)

  • Article

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

See also

BCryptDeriveKey

NCryptKeyDerivation