Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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.

KDFParameterRequired
SP800-108 HMAC in counter modeKDF_LABELyes
KDF_CONTEXTyes
KDF_HASH_ALGORITHMyes
SP800-56AKDF_ALGORITHMIDyes
KDF_PARTYUINFOyes
KDF_PARTYVINFOyes
KDF_HASH_ALGORITHMyes
KDF_SUPPPUBINFOno
KDF_SUPPPRIVINFOno
PBKDF2KDF_HASH_ALGORITHMyes
KDF_SALTyes
KDF_ITERATION_COUNTno
CAPI_KDFKDF_HASH_ALGORITHMyes

 

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.

ValueMeaning
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 only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Bcrypt.h

Library

Bcrypt.lib

DLL

Bcrypt.dll

See also

BCryptDeriveKey
NCryptKeyDerivation

 

 

Show: