共用方式為

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 基底密碼編譯提供者 會產生 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 位。 這些長度與列舉演算法時所傳回的長度不同，其中 dwParam 值 CryptGetProvParam 函式設定為 PP_ENUMALGS。 這個呼叫傳回的長度是金鑰的實際大小，包括金鑰中包含的同位位。

Microsoft支援該演算法 CALG_CYLINK_MEKALG_ID 傳回 64 位的 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
允許 訊息驗證碼 （MAC） 與金鑰搭配使用。
CRYPT_READ
允許讀取值。
CRYPT_WRITE
允許設定值。
 

如果 數位簽名標準 （DSS） 索引鍵是由 hKey 參數指定，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：從匯入的 Diffie-Hellman 演算法擷取秘密合約值，CALG_AGREEDKEY_ANY類型的索引鍵。 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 所產生。 某些可能的錯誤碼包括下列各項。

傳回碼 描述
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 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 wincrypt.h
連結庫 Advapi32.lib
DLL Advapi32.dll

另請參閱

CryptSetKeyParam

金鑰產生和 Exchange 函式