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.

KDFParameterRequired
SP800-108 HMAC in counter modeKDF_LABELyes
KDF_CONTEXTyes
KDF_HASH_ALGORITHMyes
SP800-56AKDF_ALGORITHMIDyes
KDF_PARTYUINFOyes
KDF_PARTYVINFOyes
KDF_HASH_ALGORITHMyes
KDF_SUPPPUBINFOno
KDF_SUPPPRIVINFOno
PBKDF2KDF_HASH_ALGORITHMyes
KDF_SALTyes
KDF_ITERATION_COUNTno
CAPI_KDFKDF_HASH_ALGORITHMyes

 

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.

ValueMeaning
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 codeDescription
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

Minimum supported client

Windows 8 [desktop apps only]

Minimum supported server

Windows Server 2012 [desktop apps only]

Header

Ncrypt.h

Library

Ncrypt.lib

DLL

Ncrypt.dll

See also

BCryptKeyDerivation
NCryptDeriveKey

 

 

Community Additions

ADD
Show:
© 2014 Microsoft