CryptSetKeyParam 函式 (wincrypt.h)
Microsoft 基底密碼編譯提供者不允許設定密鑰交換或簽章密鑰的值;不過，自定義提供者可以定義可為其索引鍵設定的值。
語法
BOOL CryptSetKeyParam(
[in] HCRYPTKEY hKey,
[in] DWORD dwParam,
[in] const BYTE *pbData,
[in] DWORD dwFlags
);
參數
[in] hKey
要設定值之索引鍵的句柄。
[in] dwParam
下表包含可使用的預先定義值。
對於所有索引鍵類型，此參數可以包含下列其中一個值。
| 值 | 意義 |
|---|---|
|
pbData 指向適當的 ALG_ID。 當與 Microsoft Base 數位簽名標準 (DSS) 、Diffie-Hellman 密碼編譯提供者或相容的 CSP 交換會話密鑰時，會使用此金鑰。 在與 CryptImportKey 函式同意金鑰之後，會話密鑰會藉由設定其演演算法類型來啟用以供使用。 |
|
pbData 是包含 X.509 憑證的緩衝區位址，該憑證已使用 可辨別編碼規則 (DER) 進行編碼。 憑證中的公鑰必須符合對應的簽章或交換金鑰。 |
|
pbData 指向指定零個或多個許可權旗標的 DWORD 值。 如需這些旗標的描述，請參閱 CryptGetKeyParam。 |
|
pbData 指向 BYTE 陣列，指定要成為會話索引鍵一部分的新 salt 值 。 salt 值的大小會根據所使用的 CSP 而有所不同。 在設定此值之前，呼叫 CryptGetKeyParam 函式來判斷 salt 值的大小。 Salt 值可用來讓會話索引鍵更獨特，這會使字典攻擊更加困難。 Microsoft 基底密碼編譯提供者預設為零的 salt 值。 |
|
pbData 指向包含 salt 的CRYPT_INTEGER_BLOB 結構。 如需詳細資訊，請參閱 指定 Salt 值。 |
如果 hKey 參數指定數位簽名標準 (DSS) 密鑰，dwParam 值也可以設定為下列其中一個值。
| 值 | 意義 |
|---|---|
|
pbData 會從 DSS 金鑰 BLOB 指向產生器 G。 數據的格式為 CRYPT_INTEGER_BLOB 結構，其中 pbData 成員是值， 而 cbData 成員是值的長度。 值必須是沒有標頭資訊，且 格式為小到尾 。 |
|
pbData 指向 DSS 金鑰 BLOB 的質數模數 P。 數據的格式為 CRYPT_INTEGER_BLOB 結構。 pbData 成員是值，cbData 成員是值的長度。 值必須是沒有標頭資訊，且 格式為小到尾 。 |
|
pbData 指向 DSS 金鑰 BLOB 的質 Q。 數據的格式為 CRYPT_INTEGER_BLOB 結構，其中 pbData 成員是值， 而 cbData 成員是值的長度。 值必須是沒有標頭資訊，且 格式為小到尾 。 |
|
設定 P、Q 和 G 值之後，即可對 CryptSetKeyParam 函式指定 dwParam 的KP_X值和 NULL 呼叫。 這會導致產生 X 和 Y 值。 |
如果 Diffie-Hellman 演演算法 或 數位簽名演算法 (DSA) 金鑰是由 hKey 指定， 則 dwParam 值也可以設定為下列其中一個值。
| 值 | 意義 |
|---|---|
|
設定匯入 Diffie-Hellman 金鑰的資訊。 pbData 參數是CMS_DH_KEY_INFO結構的位址，其中包含要設定的密鑰資訊。 |
|
設定 DSS 或 Diffie-Hellman 金鑰) (P、Q、G 等公用參數。 此金鑰的金鑰句柄必須處於 PREGEN 狀態，並使用 CRYPT_PREGEN 旗標產生。 pbData 參數必須是DATA_BLOB結構的指標，其中此結構中的數據是DHPUBKEY_VER3或DSSPUBKEY_VER3 BLOB。 函式會將公用參數從這個 CRYPT_INTEGER_BLOB 結構複製到密鑰句柄。 進行此呼叫之後，KP_X參數值應該與 CryptSetKeyParam 搭配使用，以建立實際的私鑰。 KP_PUB_PARAMS參數是用來做為一個呼叫，而不是使用參數值KP_P、KP_Q和KP_G的多個呼叫。 |
如果區塊 加密會話密鑰 是由 hKey 參數指定， dwParam 值也可以設定為下列其中一個值。
| 值 | 意義 |
|---|---|
|
這個實值類型只能與 RC2 金鑰搭配使用，而且因為 Windows 2000 之前的 Microsoft 增強式密碼編譯提供者中 CryptSetKeyParam 函式的實作而新增。 在先前的實作中，增強提供者中的 RC2 索引鍵強度為 128 位，但用來將索引鍵擴充至索引鍵數據表的有效密鑰長度只有 40 位。 這會將演算法的強度減少為40位。 為了維持回溯相容性，先前的實作會維持原狀。 不過，在 CryptSetKeyParam 呼叫中使用 KP_EFFECTIVE_KEYLEN，可以將有效密鑰長度設定為大於 40 位。 有效金鑰長度會在 pbData 參數中傳遞為具有有效密鑰長度值的 DWORD 值的指標。 Microsoft 基底密碼編譯提供者上的有效密鑰長度下限為一，最大值為 40。 在 Microsoft 增強式密碼編譯提供者中，最小值為一，最大值為 1,024。 密鑰長度必須先設定，才能使用金鑰加密或解密。 |
|
設定允許的最高 傳輸層安全性 (TLS) 版本。 此屬性僅適用於 SSL 和 TLS 金鑰。 pbData 參數是 DWORD 變數的位址，其中包含支援的最高 TLS 版本號碼。 |
|
pbData 指向指定初始化向量的 BYTE 陣列。 此陣列必須包含 BlockLength/8 元素。 例如，如果區塊長度是64位，初始化向量會由8個字節組成。
根據預設，初始化向量會設定為零，以供 Microsoft 基底密碼編譯提供者使用。 |
|
設定 數據加密標準 (DES) 金鑰的金鑰值。 pbData 參數是包含索引鍵的緩衝區位址。 這個緩衝區的長度必須與索引鍵相同。 此屬性僅適用於 DES 金鑰。 |
|
設定填補模式。 pbData 參數是 DWORD 值的指標，可接收識別加密所使用的填補方法的數值識別符。 這可以是下列其中一個值。 |
|
pbData 指向 DWORD 值，指定要使用的 加密模式 。 如需已定義加密模式的清單，請參閱 CryptGetKeyParam。 根據預設，加密模式會設定為 Microsoft 基底密碼編譯提供者的 CRYPT_MODE_CBC。 |
|
pbData 指向 DWORD 值，指出使用 CFB (加密模式時， 輸出意見 反應 (OF) B) 或 加密意見 反應時，每個週期處理的位數。 根據預設，每個周期處理的位數目會設定為8，以供 Microsoft 基底密碼編譯提供者使用。 |
如果在 hKey 參數中指定 RSA 金鑰，dwParam 參數值可以是下列值。
| 值 | 意義 |
|---|---|
|
設定金鑰的最佳非對稱加密填補 (OAEP) (PKCS #1 第 2 版) 參數。 pbData 參數是包含 OAEP 標籤CRYPT_DATA_BLOB結構的位址。 此屬性僅適用於 RSA 金鑰。 |
請注意，不會使用下列值：
- KP_ADMIN_PIN
- KP_CMS_KEY_INFO
- KP_INFO
- KP_KEYEXCHANGE_PIN
- KP_PRECOMP_MD5
- KP_PRECOMP_SHA
- KP_PREHASH
- KP_PUB_EX_LEN
- KP_PUB_EX_VAL
- KP_RA
- KP_RB
- KP_ROUNDS
- KP_RP
- KP_SIGNATURE_PIN
- KP_Y
[in] pbData
在呼叫 CryptSetKeyParam 之前，以要設定的值初始化之緩衝區的指標。 此數據的形式會根據 dwParam 的值而有所不同。
[in] dwFlags
只有在 dwParam KP_ALGID時才使用。 dwFlags 參數可用來傳入已啟用索引鍵的旗標值。 dwFlags 參數可以使用 CryptGenKey 產生相同類型的索引鍵時，保留密鑰大小和其他旗標值等值。 如需允許旗標值的相關信息，請參閱 CryptGenKey。
傳回值
如果函式成功，則傳回值為非零 (TRUE) 。
如果函式失敗，則傳回值為零， (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError。
由 「NTE」 開頭的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。
| 傳回碼 | Description |
|---|---|
|
CSP 內容目前正由另一個 進程使用。 |
|
其中一個參數指定無效的句柄。 |
|
其中一個參數包含無效的值。 這通常是無效的指標。 |
|
dwFlags 參數為非零，或 pbData 緩衝區包含無效的值。 |
|
dwParam 參數會指定未知的參數。 |
|
找不到 建立 hKey 金鑰時所指定的 CSP 內容。 |
|
函式以非預期的方式失敗。 |
|
某些 CSP 具有硬式編碼的 P、Q 和 G 值。 如果是這種情況，則針對 dwParam 的值使用KP_P、KP_Q和KP_G會導致此錯誤。 |
備註
如果在 PREGEN Diffie-Hellman 或 DSS 金鑰上設定KP_Q、KP_P或KP_X參數，則密鑰長度必須與使用 CryptGenKey 建立金鑰時，使用 dwFlags 參數的上限 16 位設定密鑰長度相容。 如果未在 CryptGenKey 中設定金鑰長度，則會使用預設密鑰長度。 如果使用非預設密鑰長度來設定 P、Q 或 X，這會建立錯誤。
範例
如需使用此函式的範例，請參閱 範例 C 程式：複製會話密鑰。 如需使用此函式的詳細資訊，請參閱 範例 C 程式：設定和取得工作階段金鑰參數 。
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限傳統型應用程式] |
| 目標平台 | Windows |
| 標頭 | wincrypt.h |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |
另請參閱
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應