BCryptDeriveKey 函式（bcrypt.h）

發行項
07/16/2024

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）金鑰衍生函式。

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 演演算法識別碼，適用於 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”）

傳回未經修改之原始秘密的小結束表示法。

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_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

如果 pwszKDF 參數設定為 BCRYPT_KDF_RAW_SECRET，則傳回的秘密（不同於其他 pwszKDF 值）會以小端格式編碼。在任何其他 CNG 函式中使用原始秘密時，請務必注意這一點，因為大部分函式都採用大端編碼的輸入。

根據提供者支持的處理器模式，BCryptDeriveKey 可以從使用者模式或核心模式呼叫。核心模式呼叫端可以在 IRQL PASSIVE_LEVEL或 DISPATCH_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

共用方式為

BCryptDeriveKey 函式（bcrypt.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”）

BCRYPT_KDF_RAW_SECRET （L“TRUNCATE”）

傳回值

言論

要求

另請參閱

意見反應

其他資源

共用方式為

BCryptDeriveKey 函式 （bcrypt.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”）

BCRYPT_KDF_RAW_SECRET （L“TRUNCATE”）

傳回值

言論

要求

另請參閱

意見反應

其他資源

BCryptDeriveKey 函式（bcrypt.h）