Edit

BCryptDeriveKeyCapi function (bcrypt.h)

  • Article

The BCryptDeriveKeyCapi function derives a key from a hash value.

This function is provided as a helper function to assist in migrating legacy Cryptography API (CAPI)–based applications to use Cryptography API: Next Generation (CNG). The BCryptDeriveKeyCapi function performs the key derivation in a manner that is compatible with the CAPI CryptDeriveKey function.

Syntax

NTSTATUS BCryptDeriveKeyCapi(
  [in]           BCRYPT_HASH_HANDLE hHash,
  [in, optional] BCRYPT_ALG_HANDLE  hTargetAlg,
  [out]          PUCHAR             pbDerivedKey,
  [in]           ULONG              cbDerivedKey,
  [in]           ULONG              dwFlags
);

Parameters

[in] hHash

The handle of the hash object. The handle is obtained by calling the BCryptCreateHash function. When you have finished using the handle, you must free it by calling the BCryptDestroyHash function.

[in, optional] hTargetAlg

The handle of the algorithm object. This can be an ALG_ID value that is compatible with the CryptDeriveKey function.

Note  Limitations in CAPI and key expansion prevent the use of any hash algorithm that generates an output that is larger than 512 bits.
 

[out] pbDerivedKey

A pointer to the buffer that receives the derived key.

[in] cbDerivedKey

The size, in characters, of the derived key pointed to by the pbDerivedKey parameter.

[in] dwFlags

This parameter is reserved and must be set to zero.

Return value

Returns a status code that indicates the success or failure of the function.

Possible return codes include, but are not limited to, the following.

Return code Description
STATUS_SUCCESS
 The function was successful.
STATUS_INVALID_HANDLE
 The handle in the hHash or hTargetAlg parameter is not valid.
STATUS_INVALID_PARAMETER
 The value in the cbDerivedKey parameter is larger than twice the output size of the hash function.
STATUS_NO_MEMORY
 A memory allocation failure occurred.

Remarks

This function does not support the PK salt functionality of the CAPI CryptDeriveKey function.

Requirements

Requirement Value
Minimum supported client Windows 7 [desktop apps | UWP apps]
Minimum supported server Windows Server 2008 R2 [desktop apps | UWP apps]
Target Platform Windows
Header bcrypt.h
Library Bcrypt.lib
DLL Bcrypt.dll