BCryptDeriveKey

The BCryptDeriveKey function derives a key from a secret agreement value.

Syntax

NTSTATUS BCryptDeriveKey(
         BCRYPT_SECRET_HANDLE hSharedSecret,
         LPCWSTR pwszKDF,
         BCryptBufferDesc *pParameterList,
         PUCHAR pbDerivedKey,
         ULONG cbDerivedKey,
         ULONG *pcbResult,
         ULONG dwFlags
)  

Parameters

hSharedSecret
Type: BCRYPT_SECRET_HANDLE 

[in] The secret agreement handle to create the key from. This handle is obtained from the BCryptSecretAgreement function.

pwszKDF
Type: LPCWSTR 

[in] A pointer to a null-terminated Unicode string that identifies the key derivation function (KDF) to use to derive the key. This can be one of the following strings.

pParameterList
Type: BCryptBufferDesc *

[in, optional] The address of a BCryptBufferDesc structure that contains the KDF parameters. This parameter is optional and can be NULL if it is not needed.

pbDerivedKey
Type: PUCHAR 

[out, optional] The address of a buffer that receives the key. The cbDerivedKey parameter contains the size of this buffer. If this parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by the pcbResult parameter.

cbDerivedKey
Type: ULONG 

[in] The size, in bytes, of the pbDerivedKey buffer.

pcbResult
Type: ULONG *

[out] A pointer to a ULONG that receives the number of bytes that were copied to the pbDerivedKey buffer. If the pbDerivedKey parameter is NULL, this function will place the required size, in bytes, in the ULONG pointed to by this parameter.

dwFlags
Type: ULONG 

[in] A set of flags that modify the behavior of this function. This can be zero or the following value.

Return value

Type: NTSTATUS 

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

Return codes

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

Remarks

The BCryptBufferDesc structure in the pParameterList parameter can contain more than one of the KDF_SECRET_PREPEND and KDF_SECRET_APPEND parameters. If more than one of these parameters is specified, the parameter values are concatenated in the order in which they are contained in the array before the KDF is called. For example, assume the following parameter values are specified.

Example

If the above parameter values are specified, the concatenated values to the actual KDF are as follows.

Example

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4  

Depending on what processor modes a provider supports, BCryptDeriveKey can be called either from user mode or kernel mode. Kernel mode callers can execute either at PASSIVE_LEVELIRQL or DISPATCH_LEVEL IRQL. If the current IRQL level is DISPATCH_LEVEL, the handle provided in the hSharedSecret parameter must be located in nonpaged (or locked) memory and must be derived from an algorithm handle returned by a provider that was opened by using the BCRYPT_PROV_DISPATCH flag.

Requirements

Header: Declared in bcrypt.h.

Library: Use bcrypt.lib.