NCryptDeriveKey 函数 (ncrypt.h)

项目
02/29/2024

NCryptDeriveKey 函数从机密协议值派生密钥。此函数旨在用作使用持久机密协议密钥的机密协议过程的一部分。若要改用持久机密派生密钥材料，请使用 NCryptKeyDerivation 函数。

语法

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

参数

[in] hSharedSecret

要从中创建密钥的机密协议句柄。此句柄是从 NCryptSecretAgreement 函数获取的。

[in] pwszKDF

指向以 null 结尾的 Unicode 字符串的指针，该字符串标识密钥 派生函数 (KDF) 用于派生密钥。这可以是以下字符串之一。

BCRYPT_KDF_HASH (L“HASH”)

使用哈希键派生函数。

如果 cbDerivedKey 参数小于派生密钥的大小，则此函数将仅将指定的字节数复制到 pbDerivedKey 缓冲区。如果 cbDerivedKey 参数大于派生键的大小，则此函数会将密钥复制到 pbDerivedKey 缓冲区，并将 由印刷品指向 的变量设置为复制的实际字节数。

pParameterList 参数标识的参数可以或必须包含以下参数，如必需列或可选列所指示的那样。

参数	说明	必需还是可选
KDF_HASH_ALGORITHM	一个以 null 结尾的 Unicode 字符串，用于标识要使用的哈希算法。这可以是 CNG 算法标识符中的标准哈希算法标识符之一，也可以是另一个已注册哈希算法的标识符。如果未指定此参数，则使用 SHA1 哈希算法。	可选
KDF_SECRET_PREPEND	要添加到哈希函数的消息输入的开头的值。有关详细信息，请参阅“备注”。	可选
KDF_SECRET_APPEND	要添加到哈希函数的消息输入末尾的值。有关详细信息，请参阅“备注”。	可选

调用 KDF，如以下伪代码所示。

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC (L“HMAC”)

使用基于哈希的消息身份验证代码 (HMAC) 密钥派生函数。

pParameterList 参数标识的参数可以或必须包含以下参数，如必需列或可选列所指示的那样。

参数	说明	必需还是可选
KDF_HASH_ALGORITHM	一个以 null 结尾的 Unicode 字符串，用于标识要使用的哈希算法。这可以是 CNG 算法标识符中的标准哈希算法标识符之一，也可以是另一个已注册哈希算法的标识符。如果未指定此参数，则使用 SHA1 哈希算法。	可选
KDF_HMAC_KEY	要用于伪随机函数的密钥 (PRF) 。	可选
KDF_SECRET_PREPEND	要添加到哈希函数的消息输入的开头的值。有关详细信息，请参阅“备注”。	可选
KDF_SECRET_APPEND	要添加到哈希函数的消息输入末尾的值。有关详细信息，请参阅“备注”。	可选

调用 KDF，如以下伪代码所示。

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF (L“TLS_PRF”)

使用传输层安全性 (TLS) 伪随机函数 (PRF) 密钥派生函数。派生密钥的大小始终为 48 字节，因此 cbDerivedKey 参数必须为 48。

pParameterList 参数标识的参数可以或必须包含以下参数，如必需列或可选列所指示的那样。

参数	说明	必需还是可选
KDF_TLS_PRF_LABEL	包含 PRF 标签的 ANSI 字符串。	必需
KDF_TLS_PRF_SEED	PRF 种子。种子的长度必须为 64 个字节。	必需

调用 KDF，如以下伪代码所示。

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT (L“SP800_56A_CONCAT”)

使用 SP800-56A 密钥派生函数。

pParameterList 参数标识的参数可以或必须包含以下参数，如必需列或可选列所指示的那样。所有参数值都被视为不透明的字节数组。

参数	说明	必需还是可选
KDF_ALGORITHMID	指定 SP800-56A 密钥派生函数中 OtherInfo 字段的 AlgorithmID 子字段。指示派生密钥的预期用途。	必需
KDF_PARTYUINFO	指定 SP800-56A 密钥派生函数中 OtherInfo 字段的 PartyUInfo 子字段。字段包含发起方提供的公共信息。	必需
KDF_PARTYVINFO	指定 SP800-56A 密钥派生函数中 OtherInfo 字段的 PartyVInfo 子字段。字段包含响应者提供的公共信息。	必需
KDF_SUPPPUBINFO	在 SP800-56A 密钥派生函数中指定 OtherInfo 字段的 SuppPubInfo 子字段。字段包含发起方和响应方已知的公共信息。	可选
KDF_SUPPPRIVINFO	指定 SP800-56A 密钥派生函数中 OtherInfo 字段的 SuppPrivInfo 子字段。它包含发起方和响应方已知的私人信息，例如共享机密。	可选

调用 KDF，如以下伪代码所示。

KDF-Output = SP_800-56A_KDF(
	   hSharedSecret,
	   KDF_ALGORITHMID,
	   KDF_PARTYUINFO,
	   KDF_PARTYVINFO,
	   KDF_SUPPPUBINFO,
	   KDF_SUPPPRIVINFO)

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此值。

[in, optional] pParameterList

包含 KDF 参数的 NCryptBufferDesc 结构的地址。此参数是可选的，如果不需要此参数，可为 NULL 。

[out, optional] pbDerivedKey

接收密钥的缓冲区的地址。 cbDerivedKey 参数包含此缓冲区的大小。如果此参数为 NULL，则此函数会将所需大小（以字节为单位）放置在由该参数指向的 DWORD 中。

[in] cbDerivedKey

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

[out] pcbResult

指向 DWORD 的指针，该 DWORD 接收复制到 pbDerivedKey 缓冲区的字节数。如果 pbDerivedKey 参数为 NULL，则此函数会将所需的大小（以字节为单位）放置在此参数指向的 DWORD 中。

[in] dwFlags

一组标志，用于修改此函数的行为。这可以是零或以下值。

值	含义
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	机密协议值也将用作 HMAC 密钥。如果指定了此标志，则 KDF_HMAC_KEY 参数不应包含在 pParameterList 参数的参数集中。此标志仅由 BCRYPT_KDF_HMAC 密钥派生函数使用。

返回值

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

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

返回代码	说明
ERROR_SUCCESS	函数成功。
NTE_INVALID_HANDLE	hSharedSecret 参数无效。
NTE_INVALID_PARAMETER	一个或多个参数无效。

注解

pParameterList 参数中的 BCryptBufferDesc 结构可以包含多个KDF_SECRET_PREPEND和KDF_SECRET_APPEND参数。如果指定了其中多个参数，则参数值将按照在调用 KDF 之前包含在数组中的顺序进行连接。例如，假设指定了以下参数值。

BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof  (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

如果指定了上述参数值，则实际 KDF 的串联值如下所示。

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

服务不得从其 StartService 函数调用此函数。如果服务从其 StartService 函数调用此函数，则可能会出现死锁，并且服务可能会停止响应。

要求

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

另请参阅

NCryptBufferDesc

通过

NCryptDeriveKey 函数 (ncrypt.h)

语法

参数

BCRYPT_KDF_HASH (L“HASH”)

BCRYPT_KDF_HMAC (L“HMAC”)

BCRYPT_KDF_TLS_PRF (L“TLS_PRF”)

BCRYPT_KDF_SP80056A_CONCAT (L“SP800_56A_CONCAT”)

返回值

注解

要求

另请参阅

反馈

其他资源