BCryptDeriveKey 函数 (bcrypt.h)

BCryptDeriveKey 函数从机密协议值派生密钥。

有关从给定机密派生的密钥,请参阅 BCryptKeyDerivation

语法

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

参数

[in] hSharedSecret

用于从中创建密钥的机密协议句柄。 此句柄是从 BCryptSecretAgreement 函数获取的。

[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”)

使用 Hash-Based 消息身份验证代码(HMAC)密钥派生函数。

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

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_TLS_PRF_PROTOCOL DWORD 值,该值指定要使用的 PRF 算法的 TLS 协议版本。

有效值为:

SSL2_PROTOCOL_VERSION(0x0002)
SSL3_PROTOCOL_VERSION(0x0300)
TLS1_PROTOCOL_VERSION(0x0301)
TLS1_0_PROTOCOL_VERSION(0x0301)
TLS1_1_PROTOCOL_VERSION(0x0302)
TLS1_2_PROTOCOL_VERSION(0x0303)
DTLS1_0_PROTOCOL_VERSION(0xfeff)

Windows Server 2008 和 Windows Vista:不支持 TLS1_1_PROTOCOL_VERSION、TLS1_2_PROTOCOL_VERSION和DTLS1_0_PROTOCOL_VERSION。

Windows Server 2008 R2、Windows 7、Windows Server 2008 和 Windows Vista:不支持 DTLS1_0_PROTOCOL_VERSION。

自选
KDF_HASH_ALGORITHM 要与 PRF 中的 HMAC 一起使用的哈希的 CNG 算法 ID,用于 TLS 1.2 协议版本。 有效选项为 SHA-256 和 SHA-384。 如果未指定,则使用 SHA-256。 自选
 

对 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:不支持此值。

BCRYPT_KDF_RAW_SECRET (L“TRUNCATE”)

返回原始机密的 little-endian 表示形式,无需进行任何修改。

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

Windows 8、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP:不支持此值

[in, optional] pParameterList

包含 KDF 参数的 BCryptBufferDesc 结构的地址。 此参数是可选的,如果需要,则可以 NULL

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

pbDerivedKey 缓冲区的大小(以字节为单位)。

[out] pcbResult

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

[in] dwFlags

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

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

返回值

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

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

返回代码 描述
STATUS_SUCCESS
函数成功。
STATUS_INTERNAL_ERROR
发生内部错误。
STATUS_INVALID_HANDLE
hSharedSecret 参数中的句柄无效。
STATUS_INVALID_PARAMETER
一个或多个参数无效。

言论

pParameterList 参数中的 BCryptBufferDesc 结构可以包含多个 KDF_SECRET_PREPENDKDF_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

如果 pwszKDF 参数设置为 BCRYPT_KDF_RAW_SECRET,则返回的机密(与其他 pwszKDF 值不同)将以小端格式进行编码。 在任何其他 CNG 函数中使用原始机密时,请务必注意这一点,因为其中大多数函数采用大端编码输入。

根据提供程序支持的处理器模式,BCryptDeriveKey 可以从用户模式或内核模式调用。 内核模式调用方可以在 PASSIVE_LEVELIRQLDISPATCH_LEVEL IRQL 上执行。 如果当前 IRQL 级别 DISPATCH_LEVEL,则 hSharedSecret 参数中提供的句柄必须位于非分页(或锁定)内存中,并且必须派生自使用 BCRYPT_PROV_DISPATCH 标志打开的提供程序返回的算法句柄。

若要在内核模式下调用此函数,请使用 Cng.lib,这是驱动程序开发工具包(DDK)的一部分。 Windows Server 2008 和 Windows Vista:若要在内核模式下调用此函数,请使用 Ksecdd.lib。

要求

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

另请参阅

BCryptSecretAgreement