NCryptKeyDerivation function

The NCryptKeyDerivation function creates a key from another key by using the specified key derivation function. The function returns the key in a byte array.

Syntax

SECURITY_STATUS WINAPI NCryptKeyDerivation(
  _In_  NCRYPT_KEY_HANDLE hKey,
  _In_  NCryptBufferDesc  *pParameterList,
  _Out_ PUCHAR            pbDerivedKey,
  _In_  DWORD             cbDerivedKey,
  _Out_ DWORD             *pcbResult,
  _In_  ULONG             dwFlags
);

Parameters

hKey [in]

Handle of the key derivation function (KDF) key.

pParameterList [in]

The address of a NCryptBufferDesc structure that contains the KDF parameters. The parameters can be specific to a KDF or generic. The following table shows the required and optional parameters for specific KDFs implemented by the Microsoft software key storage 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 [out]

Address of a buffer that receives the key. The cbDerivedKey parameter contains the size, in bytes, of the key buffer.

cbDerivedKey [in]

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

pcbResult [out]

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

dwFlags [in]

Flags that modify function behavior. The following value can be used with the Microsoft software key storage 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.
NCRYPT_SILENT_FLAG	Requests that the key service provider (KSP) not display any user interface. If the provider must display the UI to operate, the call fails and the KSP should set the NTE_SILENT_CONTEXT error code as the last error.

 

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.

Remarks

You can use the following algorithm identifiers in the NCryptCreatePersistedKey function before calling NCryptKeyDerivation:

• BCRYPT_CAPI_KDF_ALGORITHM
• BCRYPT_SP800108_CTR_HMAC_ALGORITHM
• BCRYPT_SP80056A_CONCAT_ALGORITHM
• BCRYPT_PBKDF2_ALGORITHM

Requirements

See also

BCryptKeyDerivation

NCryptDeriveKey