CryptSetKeyParam 函式 （wincrypt.h）

  • 發行項
重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 在未來版本中可能會移除此 API。
 
CryptSetKeyParam 函式會自定義會話密鑰作業的各個層面。 此函式所設定的值不會保存在記憶體中，而且只能在單一會話中使用。

Microsoft 基底密碼編譯提供者 不允許設定密鑰交換或簽章密鑰的值;不過，自定義提供者可以定義可為其索引鍵設定的值。

語法

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

參數

[in] hKey

要設定值之索引鍵的句柄。

[in] dwParam

下表包含可使用的預先定義值。

對於所有索引鍵類型，此參數可以包含下列其中一個值。

價值 意義
KP_ALGID
 pbData 指向適當的 ALG_ID。 這在與 Microsoft 基底數位簽名標準 （DSS）、Diffie-Hellman 密碼編譯提供者或相容的 CSP 交換會話密鑰時使用。 當密鑰與 CryptImportKey 函式達成一致之後，會話密鑰會藉由設定其演算法類型來啟用以供使用。
KP_CERTIFICATE
 pbData 是緩衝區位址，其中包含使用 辨別編碼規則 （DER） 編碼的 X.509 憑證。 憑證中的公鑰必須符合對應的簽章或交換金鑰。
KP_PERMISSIONS
 pbData 指向指定零或多個許可權旗標的 DWORD 值。 如需這些旗標的描述，請參閱 CryptGetKeyParam。
KP_SALT
 pbData 指向 BYTE 陣列，指定要成為會話索引鍵一部分的新 salt 值。 salt 值的大小會根據所使用的 CSP 而有所不同。 設定此值之前，請先呼叫 cryptGetKeyParam 函式，以判斷 salt 值的大小。 Salt 值可用來讓會話索引鍵更具獨特性，這會使字典攻擊更加困難。 根據預設，Microsoft基底密碼編譯提供者的 salt 值為零。
KP_SALT_EX
 pbData 指向包含 salt 的 CRYPT_INTEGER_BLOB 結構。 如需詳細資訊，請參閱 指定 Salt 值。
 

如果 數位簽名標準 （DSS） 索引鍵是由 hKey 參數指定，dwParam 值也可以設定為下列其中一個值。

價值 意義
KP_G
 pbData 從 DSS 金鑰 BLOB指向產生器 G。 數據的格式為 CRYPT_INTEGER_BLOB 結構，其中 pbData 成員是值，而 cbData 成員是值的長度。 值必須是沒有標頭資訊，而且在 窗體中。
KP_P
 pbData 指向 DSS 金鑰 BLOB 的主要模數 P。 數據的格式為 CRYPT_INTEGER_BLOB 結構。 pbData 成員是值，而 cbData 成員 為值的長度。 值必須是沒有標頭資訊，而且在 窗體中。
KP_Q
 pbData 指向 DSS 金鑰 BLOB 的主要 Q。 數據的格式為 CRYPT_INTEGER_BLOB 結構，其中 pbData 成員是值 ，而 cbData 成員則為值的長度。 值必須是沒有標頭資訊，而且在 窗體中。
KP_X
 設定 P、Q 和 G 值之後，呼叫會指定 dwParam 的KP_X值，並針對 pbData 參數 NULL，對 CryptSetKeyParam 函式進行。 這會導致產生 X 和 Y 值。
 

如果 Diffie-Hellman 演演算法 或 數位簽名演算法 （DSA） 索引鍵是由 hKey指定，dwParam 值也可以設定為下列其中一個值。

價值 意義
KP_CMS_DH_KEY_INFO
 設定匯入 Diffie-Hellman 鍵的資訊。 pbData 參數是包含要設定之密鑰資訊的 CMS_DH_KEY_INFO 結構位址。
KP_PUB_PARAMS
 設定 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 值也可以設定為下列其中一個值。

價值 意義
KP_EFFECTIVE_KEYLEN
 這個實值類型只能與 RC2 索引鍵搭配使用，而且因為 Windows 2000 之前的Microsoft增強式密碼編譯提供者中 CryptSetKeyParam 函式的實作而新增。 在先前的實作中，增強提供者中的 RC2 索引鍵強度為 128 位，但用來將索引鍵擴充至索引鍵數據表的有效密鑰長度只有 40 位。 這會將演算法的強度降低到 40 位。 為了維持回溯相容性，先前的實作會維持原樣。 不過，有效的密鑰長度可以使用 CryptSetKeyParam 呼叫中的KP_EFFECTIVE_KEYLEN，設定為大於 40 位。 有效密鑰長度會以有效索引鍵長度值作為 DWORD 值的指標，傳入 pbData 參數。 Microsoft基底密碼編譯提供者的有效密鑰長度下限為一，最大值為 40。 在Microsoft增強式密碼編譯提供者中，最小值為 1,024。 密鑰長度必須先設定，才能使用金鑰加密或解密。
KP_HIGHEST_VERSION
 設定允許的最高 傳輸層安全性 （TLS） 版本。 此屬性僅適用於 SSL 和 TLS 金鑰。 pbData 參數是包含支援最高 TLS 版本號碼的 DWORD 變數位址。
KP_IV
 pbData 指向指定初始化向量的 BYTE 陣列。 此陣列必須包含 BlockLength/8 元素。 例如，如果區塊長度是64位，初始化向量會包含8個字節。

根據預設，初始化向量會設定為零，Microsoft基底密碼編譯提供者。
KP_KEYVAL
 設定 數據加密標準 （DES） 金鑰的金鑰值。 pbData 參數是包含索引鍵的緩衝區位址。 這個緩衝區的長度必須與索引鍵相同。 此屬性僅適用於 DES 索引鍵。
KP_PADDING
 設定填補模式。 pbData 參數是 DWORD 值的指標，這個值會接收識別 加密所使用的 填補 方法的數值標識符。 這可以是下列其中一個值。
PKCS5_PADDING
指定 PKCS 5 （秒 6.2） 填補方法。
RANDOM_PADDING
填補會使用隨機數。 Microsoft提供的 CSP 不支援這個填補方法。
ZERO_PADDING
填補使用零。 Microsoft提供的 CSP 不支援這個填補方法。
KP_MODE
 pbData 指向 DWORD 值，指定要使用的 加密 模式。 如需已定義加密模式的清單，請參閱 CryptGetKeyParam。 根據預設，加密模式會設定為 Microsoft 基底密碼編譯提供者的 CRYPT_MODE_CBC。
KP_MODE_BITS
 pbData 指向 DWORD 值，指出使用 輸出意見反應 （OFB） 或 加密意見反應 （CFB） 加密模式時，每個周期處理的位數。 每個周期處理的位數目預設會設定為8，Microsoft基底密碼編譯提供者。
 

如果在 hKey 參數中指定 RSA 索引鍵，dwParam 參數值可以是下列值。

價值 意義
KP_OAEP_PARAMS
 設定金鑰的最佳非對稱加密填補 （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 所產生。 以下是一些可能的錯誤碼。

傳回碼 描述
ERROR_BUSY
 CSP 內容目前正由另一個 進程使用。
ERROR_INVALID_HANDLE
 其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER
 其中一個參數包含無效的值。 這通常是無效的指標。
NTE_BAD_FLAGS
 dwFlags 參數為非零，或 pbData 緩衝區包含無效的值。
NTE_BAD_TYPE
 dwParam 參數會指定未知的參數。
NTE_BAD_UID
 找不到建立 hKey 金鑰時指定的 CSP 內容。
NTE_FAIL
 函式以某種非預期的方式失敗。
NTE_FIXEDPARAMETER
 某些 CSP 具有硬式編碼的 P、Q 和 G 值。 如果是這種情況，則使用 KP_P、KP_Q 和 KP_G dwParam 的值， 會造成此錯誤。

言論

如果在 PREGEN Diffie-Hellman 或 DSS 金鑰上設定KP_Q、KP_P或KP_X參數，則密鑰 長度必須與使用使用 cryptGenKey建立密鑰 時，使用 dwFlags 參數的上限 16 位 密鑰長度相容。 如果在 CryptGenKey中未設定金鑰長度，則會使用預設密鑰長度。 如果使用非預設密鑰長度來設定 P、Q 或 X，這會建立錯誤。

例子

如需使用此函式的範例，請參閱 範例 C 程式：複製工作階段金鑰。 如需使用此函式的詳細資訊，請參閱 範例 C 程式：設定和取得工作階段金鑰參數 。

要求

要求 價值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 wincrypt.h
連結庫 Advapi32.lib
DLL Advapi32.dll

另請參閱

ALG_ID

CryptGenKey

CryptGetKeyParam

CryptImportKey

金鑰產生和 Exchange 函式