BCryptDeriveKey 函数 （bcrypt.h）

BCryptDeriveKey 函数从BCRYPT_SECRET_HANDLE派生密钥。 这通常作为机密协议过程的一部分完成。

有关调用方直接提供的机密的密钥派生，请参阅 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 缓冲区，并将 由 tcpResult 指向的变量设置为复制的实际字节数。

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

对 KDF 的调用按以下伪代码所示进行。

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

BCRYPT_KDF_HMAC （L“HMAC”）

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

如果 cbDerivedKey 参数小于派生密钥的大小，此函数将仅将指定的字节数复制到 pbDerivedKey 缓冲区。 这通常是糟糕的做法，因为它可以显著减少生成的密钥的安全强度。

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

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

对 KDF 的调用按以下伪代码所示进行。

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 的调用按以下伪代码所示进行。

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

BCRYPT_KDF_SP80056A_CONCAT （L“SP800_56A_CONCAT”）

使用 SP800-56A 密钥派生函数。 这也称为 SP800-56C rev2 单步 KDF。

KDF 采用已批准的哈希函数作为参数，但此 API 在内部选择哈希函数，将哈希算法的安全强度与用于生成机密句柄的算法相匹配。 （例如 ECDH P-256 使用 SHA256，ECDH P-384 使用 SHA384）

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

对 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 表示形式，无需进行任何修改。 使用此选项通常是不好的做法，但如果需要与不支持的 KDF 进行互作，可能需要这样做。

如果 cbDerivedKey 参数小于派生密钥的大小，此函数将仅将指定的字节数复制到 pbDerivedKey 缓冲区。 这通常是糟糕的做法，因为它可以显著减少生成的密钥的安全强度。

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

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

BCRYPT_KDF_HKDF（L“HKF”）

使用 RFC 5869 中的基于 HKF（基于 HMAC 的提取和扩展 KDF）函数。

在HKF中，从以下任一项派生密钥之间进行了区分：

1. 机密协议函数的输出，该函数不是统一随机的，被视为输入键键材料（IKM）。 几乎所有 BCryptDeriveKey 的用户都将拥有此表单的机密句柄。
2. 统一随机机密值。

第一步是从机密句柄“提取”伪随机密钥（PRK）。

此步骤是通过对具有 BCRYPT_HKDF_HASH_ALGORITHM 的机密句柄调用 BCryptSetProperty 来设置在 HKF 的 HMAC 计算中使用的哈希算法来执行的。 随后对 BCryptSetProperty 进行第二次调用，并使用以下任一方法之一：

1. 如果机密句柄表示 IKM，请使用 BCRYPT_HKDF_SALT_AND_FINALIZE 提供可选的盐值，并从 IKM 中提取 PRK 并完成机密句柄。
2. 否则，请使用 BCRYPT_HKDF_PRK_AND_FINALIZE 将机密值直接转换为 HKF PRK 并完成机密句柄。

第二步是将 PRK“展开”到输出派生密钥中。

此步骤是通过对最终的机密句柄调用 BCryptDeriveKey 来执行的。

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

对 KDF 的调用按以下伪代码所示进行。

KDF-Output = HKDF-Expand(
    hSharedSecret.PRK,
    info,
    cbDerivedKey)

Windows 10： 开始支持 HKF。

[in, optional] pParameterList

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

[out, optional] pbDerivedKey

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

[in] cbDerivedKey

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

[out] pcbResult

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

[in] dwFlags

一组标志，用于修改此函数的行为。

此值可以为零或以下值：

返回值

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

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

言论

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

BYTE abValue0[] = {0x01};
BYTE abValue1[] = {0x04, 0x05};
BYTE abValue2[] = {0x10, 0x11, 0x12};
BYTE abValue3[] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = abValue0;
Parameter[0].length = sizeof (abValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = abValue1;
Parameter[1].length = sizeof (abValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = abValue2;
Parameter[2].length = sizeof (abValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = abValue3;
Parameter[3].length = sizeof (abValue3);

如果指定了上述参数值，则实际 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 。 内核模式调用方可以在 IRQL PASSIVE_LEVEL 或 DISPATCH_LEVELIRQL 上执行。 如果当前 IRQL 级别 DISPATCH_LEVEL， 则 hSharedSecret 参数中提供的句柄必须位于非分页（或锁定）内存中，并且必须派生自使用 BCRYPT_PROV_DISPATCH 标志打开的提供程序返回的算法句柄。

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

要求

另请参阅

BCryptBufferDesc

BCryptSecretAgreement