NCryptDeriveKey 函式 (ncrypt.h)

發行項
02/29/2024

NCryptDeriveKey 函式會從秘密合約值衍生密鑰。此函式旨在作為使用保存秘密合約金鑰之秘密合約程式的一部分。若要改用保存的秘密來衍生密鑰數據，請使用 NCryptKeyDerivation 函式。

語法

SECURITY_STATUS NCryptDeriveKey(
  [in]            NCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  NCryptBufferDesc     *pParameterList,
  [out, optional] PBYTE                pbDerivedKey,
  [in]            DWORD                cbDerivedKey,
  [out]           DWORD                *pcbResult,
  [in]            ULONG                dwFlags
);

參數

[in] hSharedSecret

用來建立金鑰的秘密合約句柄。此句柄是從 NCryptSecretAgreement 函式取得。

[in] pwszKDF

Null 終止 Unicode 字串的指標，可識別用來衍生密鑰的 金鑰衍生函 式 (KDF) 。這可以是下列其中一個字串。

BCRYPT_KDF_HASH (L“HASH”)

使用哈希金鑰衍生函式。

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

pParameterList 參數所識別的參數可以或必須包含下列參數，如必要或選擇性數據行所指出。

參數	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) 金鑰衍生函式。

pParameterList 參數所識別的參數可以或必須包含下列參數，如必要或選擇性數據行所指出。

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

參數	Description	必要或選用
KDF_TLS_PRF_LABEL	包含 PRF 標籤的 ANSI 字串。	必要
KDF_TLS_PRF_SEED	PRF 種子。種子長度必須為64個字節。	必要

KDF 的呼叫會如下列虛擬程式碼所示。

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

BCRYPT_KDF_SP80056A_CONCAT (L“SP800_56A_CONCAT”)

使用SP800-56A金鑰衍生函式。

pParameterList 參數所識別的參數可以或必須包含下列參數，如必要或選擇性數據行所指出。所有參數值都會被視為不透明位元組陣列。

參數	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： 不支援這個值。

[in, optional] pParameterList

包含 KDF 參數的 NCryptBufferDesc 結構位址。此參數是選擇性的，如果不需要則為 NULL 。

[out, optional] pbDerivedKey

接收金鑰的緩衝區位址。 cbDerivedKey 參數包含此緩衝區的大小。如果此參數為 NULL，則此函式會將所需的大小，以位元組為單位，放在由 azureResult 參數所指向的 DWORD 中。

[in] cbDerivedKey

pbDerivedKey 緩衝區的大小，以位元組為單位。

[out] pcbResult

DWORD 的指標，接收複製到 pbDerivedKey 緩衝區的位元組數目。如果 pbDerivedKey 參數為 NULL，此函式會將所需的大小，以位元組為單位，放在此參數所指向的 DWORD 中。

[in] dwFlags

一組旗標，可修改此函式的行為。這可以是零或下列值。

值	意義
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	秘密合約值也會作為 HMAC 金鑰。如果指定這個旗標， KDF_HMAC_KEY 參數不應該包含在 pParameterList 參數的參數集中。此旗標僅供 BCRYPT_KDF_HMAC 密鑰衍生函式使用。

傳回值

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

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

傳回碼	Description
ERROR_SUCCESS	函式成功。
NTE_INVALID_HANDLE	hSharedSecret 參數無效。
NTE_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

服務不得從它的 StartService 函式呼叫此函式。如果服務從其 StartService 函式呼叫此函式，可能會發生死結，而且服務可能會停止回應。

規格需求

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

另請參閱

NCryptBufferDesc

共用方式為

NCryptDeriveKey 函式 (ncrypt.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”)

傳回值

備註

規格需求

另請參閱

意見反應

其他資源