CryptGetKeyParam 函式 (wincrypt.h)

  • 發行項
重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。
 
CryptGetKeyParam 函式會擷取管理金鑰作業的數據。 如果使用 Microsoft 密碼編譯服務提供者 ，則這個或任何其他函式無法取得基底對稱密鑰數據。

語法

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

參數

[in] hKey

正在查詢之金鑰的句柄。

[in] dwParam

指定所要進行的查詢類型。

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

值 意義
KP_ALGID
 擷取金鑰演演算法。 pbData 參數是ALG_ID值的指標，可接收建立密鑰時所指定演算法的標識碼。

針對 CryptGenKey 函式的 Algid 參數指定AT_KEYEXCHANGE或AT_SIGNATURE時，用來產生密鑰的演演算法識別碼取決於使用的提供者。 如需詳細資訊，請參閱 ALG_ID。
KP_BLOCKLEN
 如果會話金鑰是由 hKey 參數指定，請擷取金鑰加密的區塊長度。 pbData 參數是 DWORD 值的指標，以位為單位接收區塊長度。 對於 數據流加密，此值一律為零。

如果 hKey 指定了公開/私鑰組，請擷取金鑰組的加密數據粒度。 pbData 參數是 DWORD 值的指標，可接收位中的加密數據粒度。 例如， Microsoft Base 密碼編譯提供者 會產生 512 位 RSA 金鑰組，因此會傳回這些密鑰的 512 值。 如果 公鑰演演算法 不支援 加密，則擷取的值未定義。
KP_CERTIFICATE
 pbData 是緩衝區的位址，會接收已使用 der) (可辨別編碼規則 編碼的 X.509 憑證。 憑證中的公鑰必須符合對應的簽章或交換金鑰。
KP_GET_USE_COUNT
 不使用這個值。
KP_KEYLEN
 擷取金鑰的實際長度。 pbData 參數是 DWORD 值的指標，以位為單位接收密鑰長度。 KP_KEYLEN 可用來取得任何索引鍵類型的長度。 Microsoft 密碼編譯服務提供者 (CSP) 傳回CALG_DES的 64 位密鑰長度、CALG_3DES_112的 128 位，CALG_3DES則傳回 192 位。 當您列舉將 CryptGetProvParam 函式的 dwParam 值設為 PP_ENUMALGS 時，這些長度與傳回的長度不同。 此呼叫所傳回的長度是金鑰的實際大小，包括密鑰中包含的同位位。

支援CALG_CYLINK_MEK ALG_ID傳回該演算法 64 位的 Microsoft CSP。 CALG_CYLINK_MEK 是 40 位金鑰，但具有同位和零的索引鍵位，讓密鑰長度為 64 位。
KP_SALT
 擷取索引鍵的 salt 值 。 pbData 參數是 BYTE 陣列的指標，其會以小數端形式接收 salt 值。 Salt 值的大小會根據使用的 CSP 和演算法而有所不同。 Salt 值不適用於 公開/私鑰組。
KP_PERMISSIONS
 擷取密鑰許可權。 pbData 參數是 DWORD 值的指標，可接收密鑰的許可權旗標。

目前已定義下列許可權標識碼。 索引鍵許可權可以是零或下列一或多個值的組合。

CRYPT_ARCHIVE
允許在金鑰句柄的存留期內匯出。 只有在金鑰的內部許可權欄位中已經設定此許可權時，才能設定此許可權。 系統會忽略嘗試清除此許可權。
CRYPT_DECRYPT
允許解密。
CRYPT_ENCRYPT
允許加密。
CRYPT_EXPORT
允許匯出金鑰。
CRYPT_EXPORT_KEY
允許金鑰用於匯出金鑰。
CRYPT_IMPORT_KEY
允許金鑰用於匯入金鑰。
CRYPT_MAC
允許 將訊息驗證代碼 () 與金鑰搭配使用。
CRYPT_READ
允許讀取值。
CRYPT_WRITE
允許設定值。
 

如果 hKey 參數指定數位簽名標準 (DSS) 密鑰，dwParam 值也可以設定為下列其中一個值。

值 意義
KP_P
 擷取 DSS 金鑰的模數質數 P。 pbData 參數是緩衝區的指標，其會以小端格式接收值。 pdwDataLen 參數包含緩衝區的大小，以位元組為單位。
KP_Q
 擷取 DSS 金鑰的模數質數 Q。 pbData 參數是緩衝區的指標，其會以小端格式接收值。 pdwDataLen 參數包含緩衝區的大小，以位元組為單位。
KP_G
 擷取 DSS 金鑰的產生器 G。 pbData 參數是緩衝區的指標，其會以小端格式接收值。 pdwDataLen 參數包含緩衝區的大小，以位元組為單位。
 

如果區塊 加密會話密鑰 是由 hKey 參數指定， dwParam 值也可以設定為下列其中一個值。

值 意義
KP_EFFECTIVE_KEYLEN
 擷取 RC2 金鑰的有效金鑰長度。 pbData 參數是接收有效密鑰長度之 DWORD 值的指標。
KP_IV
 擷取索引鍵的初始化向量。 pbData 參數是接收初始化向量的 BYTE 陣列指標。 此陣列的大小是區塊大小，以位元組為單位。 例如，如果區塊長度是64位，初始化向量會由8個字節組成。
KP_PADDING
 擷取填補模式。 pbData 參數是 DWORD 值的指標，可接收識別加密所使用的填補方法的數值識別符。 這可以是下列其中一個值。
PKCS5_PADDING
指定 PKCS 5 (秒 6.2) 填補方法。
RANDOM_PADDING
填補會使用隨機數。 Microsoft 提供的 CSP 不支援此填補方法。
ZERO_PADDING
填補會使用零。 Microsoft 提供的 CSP 不支援此填補方法。
KP_MODE
 擷取 加密模式。 pbData 參數是接收加密模式標識碼之 DWORD 值的指標。 如需加密模式的詳細資訊，請參閱 數據加密和解密。

目前已定義下列加密模式識別碼。

CRYPT_MODE_CBC
加密模式是 加密區塊鏈結。
CRYPT_MODE_CFB
加密模式是加密 意見 反應， (CFB) 。 Microsoft CSP 目前僅支援加密意見反應模式中的 8 位意見反應。
CRYPT_MODE_ECB
加密模式是 電子代碼簿。
CRYPT_MODE_OFB
加密模式是 OFB) (輸出 意見 反應。 Microsoft CSP 目前不支援輸出意見反應模式。
CRYPT_MODE_CTS
加密模式是 加密文字 竊取模式。
KP_MODE_BITS
 擷取要送回的位數目。 pbData 參數是 DWORD 值的指標，可接收使用 OFB 或 CFB 加密模式時，每個週期所處理的位數。
 

如果 Diffie-Hellman 演演算法 或 數位簽名演算法 (DSA) 金鑰是由 hKey 指定， 則 dwParam 值也可以設定為下列值。

值 意義
KP_VERIFY_PARAMS
 驗證 Diffie-Hellman 演算法或 DSA 金鑰的參數。 不會使用 pbData 參數， 而 pdwDataLen 所指向的值會接收零。

如果索引鍵參數有效或零，此函式會傳回非零值。
KP_KEYVAL
 不使用這個值。

Windows Vista、Windows Server 2003 和 Windows XP： 從類型為 CALG_AGREEDKEY_ANY 的匯入 Diffie-Hellman 演演算法密鑰擷取秘密合約值。 pbData 參數是緩衝區的位址，其會以小數端格式接收秘密合約值。 這個緩衝區的長度必須與索引鍵相同。 dwFlags 參數必須設定為 0xF42A19B6。 此屬性只能由在本機系統帳戶下執行的線程擷取。此屬性可用於上面所列的操作系統。 它在後續版本中可能會變更或無法使用。
 

如果 憑證是由 hKey 指定， dwParam 值也可以設定為下列值。

值 意義
KP_CERTIFICATE
 包含 DER 編碼 X.509 憑證的緩衝區。 不會使用 pbData 參數， 而 pdwDataLen 所指向的值會接收零。

如果索引鍵參數有效或零，此函式會傳回非零值。

[out] pbData

接收數據的緩衝區指標。 此數據的格式取決於 dwParam 的值。

如果不知道這個緩衝區的大小，則可以在運行時間擷取必要的大小，方法是傳遞此參數的 NULL 並將 pdwDataLen 指向的值設定為零。 此函式會將緩衝區所需的大小，以位元組為單位，放在 pdwDataLen 所指向的值中。 如需詳細資訊，請參閱 擷取未知長度的數據。

[in, out] pdwDataLen

在專案上， DWORD 值的指標包含 pbData 參數所指向之緩衝區的大小，以位元組為單位。 當函式傳回時， DWORD 值會包含儲存在緩衝區中的位元元組數目。

注意 處理緩衝區中傳回的數據時，應用程式必須使用傳回之數據的實際大小。 實際大小可能比輸入上指定的緩衝區大小稍微小一點。 在輸入上，緩衝區大小有時會指定夠大，以確保最大可能的輸出數據符合緩衝區。 在輸出上，此參數所指向的變數會更新，以反映複製到緩衝區的數據實際大小。
 

[in] dwFlags

此參數保留供日後使用，且必須設定為零。

傳回值

如果函式成功，函式會傳回非零。

如果函式失敗，它會傳回零。 如需擴充錯誤資訊，請呼叫 GetLastError。

由 「NTE」 開頭的錯誤碼是由所使用的特定 CSP 所產生。 某些可能的錯誤碼包括下列各項。

傳回碼 Description
ERROR_INVALID_HANDLE
 其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER
 其中一個參數包含無效的值。 這通常是無效的指標。
ERROR_MORE_DATA
 如果 pbData 參數指定的緩衝區不足以保存傳回的數據，函式會設定 ERROR_MORE_DATA程序 代碼，並以位元組為單位儲存 pdwDataLen 所指向的變數中所需的緩衝區大小。
NTE_BAD_FLAGS
 dwFlags 參數為非零。
NTE_BAD_KEY或NTE_NO_KEY
 hKey 參數指定的金鑰無效。
NTE_BAD_TYPE
 dwParam 參數會指定未知的值編號。
NTE_BAD_UID
 找不到建立金鑰時指定的 CSP 內容 。

規格需求

需求 值
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 wincrypt.h
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

CryptSetKeyParam

金鑰產生和 Exchange 函式