NCryptKeyDerivation function (ncrypt.h)

Article
08/23/2022

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 NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

Parameters

[in] hKey

Handle of the key derivation function (KDF) key.

[in] pParameterList

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

[out] pbDerivedKey

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

[in] cbDerivedKey

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

[out] pcbResult

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

[in] dwFlags

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.

Return code	Description
ERROR_SUCCESS	The function was successful.
NTE_INVALID_HANDLE	The hProvider or hKey handles are not valid.
NTE_INVALID_PARAMETER	The pwszDerivedKeyAlg and pParameterList parameters cannot be NULL.
NTE_NO_MEMORY	There was not enough memory to create the key.
NTE_NOT_SUPPORTED	This function is not supported by the key storage provider.

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

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	ncrypt.h
Library	Ncrypt.lib
DLL	Ncrypt.dll