Share via

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 參數所識別的參數可以或必須包含下列參數，如 Required 或 optional 數據行所指出。

參數 Description 必要或選用
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) 金鑰衍生函式。

如果 cbDerivedKey 參數小於衍生密鑰的大小，此函式只會將指定的位元元組數目複製到 pbDerivedKey 緩衝區。 如果 cbDerivedKey 參數大於衍生金鑰的大小，則此函式會將密鑰複製到 pbDerivedKey 緩衝區，並將 由其 所指向的變數設定為複製的實際位元組數目。

pParameterList 參數所識別的參數可以或必須包含下列參數，如 Required 或 optional 數據行所指出。

參數 Description 必要或選用
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 參數所識別的參數可以或必須包含下列參數，如 Required 或 optional 數據行所指出。

參數 Description 必要或選用
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 參數所識別的參數可以或必須包含下列參數，如 Required 或 optional 數據行所指出。 所有參數值都會被視為不透明位元組陣列。

參數 Description 必要或選用
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 密鑰衍生函式使用。

傳回值

傳回狀態代碼，指出函式的成功或失敗。

可能的傳回碼包括但不限於下列專案。

傳回碼 Description
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 可以從使用者模式或核心模式呼叫。 核心模式呼叫端可以在 PASSIVE_LEVEL IRQL 或DISPATCH_LEVELIRQL 上執行。 如果目前的 IRQL 層級DISPATCH_LEVEL，hSharedSecret 參數中提供的句柄必須位於非分頁 (或鎖定) 記憶體中，而且必須衍生自使用 BCRYPT_PROV_DISPATCH 旗標開啟的提供者所傳回的演算法句柄。

若要在核心模式中呼叫此函式，請使用 Cng.lib，這是驅動程式開發工具包 (DDK) 的一部分。 Windows Server 2008 和 Windows Vista： 若要在核心模式中呼叫此函式，請使用 Ksecdd.lib。

規格需求

需求 值
最低支援的用戶端 Windows Vista [傳統型應用程式 |UWP 應用程式]
最低支援的伺服器 Windows Server 2008 [傳統型應用程式 |UWP 應用程式]
目標平台 Windows
標頭 bcrypt.h
程式庫 Bcrypt.lib
Dll Bcrypt.dll

另請參閱

BCryptSecretAgreement