NCryptKeyDerivation function (ncrypt.h)

The NCryptKeyDerivation function derives a key by invoking a Key Derivation Function (KDF), with all parameters explicitly being provided.

It is similar in functionality to NCryptDeriveKey but directly invokes a KDF algorithm, so does not require a NCRYPT_SECRET_HANDLE value as input.

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 an NCryptBufferDesc structure that contains the KDF parameters.

The parameters can be specific to a key derivation function (KDF) or generic. The following table shows the required and optional parameters for specific KDFs implemented by the Microsoft software key storage provider.

For some algorithms, the KDF_GENERIC_PARAMETER instead of specifying several parameters. This maps 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

[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

A set of flags that modify the behavior of this function. This can be zero or a combination of one or more of the following values. The set of valid flags is specific to each key storage provider.

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
• BCRYPT_TLS1_1_KDF_ALGORITHM
• BCRYPT_TLS1_2_KDF_ALGORITHM

Requirements

See also

BCryptKeyDerivation

NCryptDeriveKey