NCryptKeyDerivation 函数 (ncrypt.h)

  • 项目

NCryptKeyDerivation 函数使用指定的键派生函数从另一个键创建密钥。 函数返回字节数组中的键。

语法

SECURITY_STATUS NCryptKeyDerivation(
  [in]  NCRYPT_KEY_HANDLE hKey,
  [in]  NCryptBufferDesc  *pParameterList,
  [out] PUCHAR            pbDerivedKey,
  [in]  DWORD             cbDerivedKey,
  [out] DWORD             *pcbResult,
  [in]  ULONG             dwFlags
);

参数

[in] hKey

密钥派生函数的句柄 (KDF) 键。

[in] pParameterList

包含 KDF 参数的 NCryptBufferDesc 结构的地址。 参数可以特定于 KDF 或泛型。 下表显示了 Microsoft 软件密钥存储提供程序实现的特定 KDF 的必需和可选参数。

KDF 参数 必需
SP800-108 HMAC 处于计数器模式 KDF_LABEL 是
KDF_CONTEXT 是
KDF_HASH_ALGORITHM 是
SP800-56A KDF_ALGORITHMID 是
KDF_PARTYUINFO 是
KDF_PARTYVINFO 是
KDF_HASH_ALGORITHM 是
KDF_SUPPPUBINFO 否
KDF_SUPPPRIVINFO 否
PBKDF2 KDF_HASH_ALGORITHM 是
KDF_SALT 是
KDF_ITERATION_COUNT 否
CAPI_KDF KDF_HASH_ALGORITHM 是
 

可以使用以下泛型参数：

  • KDF_GENERIC_PARAMETER
泛型参数按以下方式映射到 KDF 特定参数：

SP800-108 HMAC 处于计数器模式：

  • 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 - 默认值为 10000

CAPI_KDF

  • KDF_GENERIC_PARAMETER = 未使用

[out] pbDerivedKey

接收密钥的缓冲区的地址。 cbDerivedKey 参数包含密钥缓冲区的大小（以字节为单位）。

[in] cbDerivedKey

pbDerivedKey 参数指向的缓冲区的大小（以字节为单位）。

[out] pcbResult

指向 DWORD 的指针，该 DWORD 接收复制到 pbDerivedKey 参数指向的缓冲区的字节数。

[in] dwFlags

用于修改函数行为的标志。 以下值可用于 Microsoft 软件密钥存储提供程序。

值 含义
BCRYPT_CAPI_AES_FLAG
 指定目标算法为 AES，因此密钥必须进行双倍扩展。 此标志仅对CAPI_KDF算法有效。
NCRYPT_SILENT_FLAG
 请求关键服务提供程序 (KSP) 不显示任何用户界面。 如果提供程序必须显示 UI 才能操作，则调用将失败，KSP 应将 NTE_SILENT_CONTEXT 错误代码设置为最后一个错误。

返回值

返回指示函数成功或失败的状态代码。

可能的返回代码包括但不限于以下内容。

返回代码 说明
ERROR_SUCCESS
 函数成功。
NTE_INVALID_HANDLE
 hProvider 或 hKey 句柄无效。
NTE_INVALID_PARAMETER
 pwszDerivedKeyAlg 和 pParameterList 参数不能为 NULL。
NTE_NO_MEMORY
 没有足够的内存来创建密钥。
NTE_NOT_SUPPORTED
 密钥存储提供程序不支持此函数。

注解

在调用 NCryptKeyDerivation 之前，可以在 NCryptCreatePersistedKey 函数中使用以下算法标识符：

  • BCRYPT_CAPI_KDF_ALGORITHM
  • BCRYPT_SP800108_CTR_HMAC_ALGORITHM
  • BCRYPT_SP80056A_CONCAT_ALGORITHM
  • BCRYPT_PBKDF2_ALGORITHM

要求

要求 值
最低受支持的客户端 Windows 8 [桌面应用 |UWP 应用]
最低受支持的服务器 Windows Server 2012 [桌面应用 |UWP 应用]
目标平台 Windows
标头 ncrypt.h
Library Ncrypt.lib
DLL Ncrypt.dll

另请参阅

BCryptKeyDerivation

NCryptDeriveKey