共用方式為

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

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

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