Edit

Share via

NCryptKeyDerivation function (ncrypt.h)

  • Article

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

See also

BCryptKeyDerivation

NCryptDeriveKey