CryptGetProvParam 函式 (wincrypt.h)
語法
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
參數
[in] hProv
查詢 CSP 目標的句柄。 必須使用 CryptAcquireContext 函式來建立此句柄。
[in] dwParam
查詢的本質。 已定義下列查詢。
| 值 | 意義 |
|---|---|
|
將 pbData 參數中的系統管理員個人識別碼 (PIN) 傳回為 LPSTR。 |
|
不會使用這個常數。 |
|
不會使用這個常數。 |
|
傳回與 hProv 句柄相關聯的憑證鏈結。 傳回的憑證鏈結 X509_ASN_ENCODING 編碼。 |
|
目前 密鑰容器 的名稱，做為 以 Null 結尾的 CHAR 字串。 此字串與 CryptAcquireContext 函式之 pszContainer 參數中傳遞的字串完全相同，以指定要使用的密鑰容器。 您可以讀取 pszContainer 參數來判斷預設金鑰容器的名稱。 |
|
Microsoft CSP 未實作。 此行為可由其他 CSP 實作。
Windowsxp： 不支援此參數。 |
|
PROV_ENUMALGS結構，其中包含所查詢 CSP 所支援之一種演算法的相關信息。
第一次讀取此值時， dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著，您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標，以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時，已達到列舉的結尾。 此函式不是安全線程，而且如果此函式用於多線程內容，則可能無法列舉所有可用的演算法。 |
|
PROV_ENUMALGS_EX結構，其中包含所查詢 CSP 所支援之一種演算法的相關信息。 傳回的結構包含演算法的詳細資訊，而不是針對PP_ENUMALGS傳回的結構。
第一次讀取此值時， dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著，您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標，以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時，已達到列舉的結尾。 如果此函式用於多線程內容，則此函式不是安全線程，而且如果此函式用於多線程內容，則可能無法列舉所有可用的演算法。 |
|
CSP 所維護的其中一個密鑰容器名稱，格式為 Null 終止 的 CHAR 字串。
第一次讀取此值時， dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著，您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標，以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時，已達到列舉的結尾。 若要列舉與計算機相關聯的密鑰容器，請先使用 CRYPT_MACHINE_KEYSET 旗標呼叫 CryptAcquireContext，然後使用 CryptAcquireContext 傳回的句柄做為 CryptGetProvParam 呼叫中的 hProv 參數。 如果此函式用於多線程內容，則此函式不是安全線程，而且如果此函式用於多線程內容，則可能無法列舉所有可用的演算法。 |
|
不會使用這個常數。 |
|
表示目前的 CSP 支援PROV_ENUMALGS_EX結構的 dwProtocols 成員。 如果此函式成功，CSP 支援PROV_ENUMALGS_EX結構的 dwProtocols 成員。 如果此函式失敗並出現 NTE_BAD_TYPE 錯誤碼，CSP 不支援 dwProtocols 成員。 |
|
不會使用這個常數。 |
|
指出 CSP 實作方式的 DWORD 值。 如需可能值的數據表，請參閱。 |
|
不會使用此查詢。 |
|
指定金鑰交換 PIN 包含在 pbData 中。 PIN 會以 Null 終止的 ASCII 字串表示。 |
|
擷取金鑰記憶體容器 的安全性描述項 。 pbData 參數是接收密鑰記憶體容器安全性描述項之SECURITY_DESCRIPTOR結構的位址。 安全性描述項會以自我相對格式傳回。 |
|
判斷 hProv 參數是否為計算機金鑰集。 pbData 參數必須是 DWORD;如果該旗標傳遞至 CryptAcquireContext 函式，DWORD 將會設定為 CRYPT_MACHINE_KEYSET 旗標。 |
|
傳回 CSP 所支援之金鑰規範值的相關信息。 索引鍵規範值會聯結在邏輯 OR 中，並在呼叫的 pbData 參數中以 DWORD 傳回。 例如，Microsoft Base Cryptographic Provider 1.0 版會傳回 DWORD 值 AT_SIGNATURE |AT_KEYEXCHANGE。 |
|
傳回 CRYPT_SEC_DESCR的 DWORD 值。 |
|
AT_KEYEXCHANGE遞增長度的位數。 這項資訊會與PP_ENUMALGS_EX值中傳回的資訊搭配使用。 使用 PP_ENUMALGS_EX 和 PP_KEYX_KEYSIZE_INC 時傳回的資訊，即可判斷AT_KEYEXCHANGE的有效密鑰長度。 然後，這些密鑰長度可以與 CryptGenKey 搭配使用。 例如，如果 CSP 列舉 CALG_RSA_KEYX (AT_KEYEXCHANGE) 最小密鑰長度為 512 位，且最大為 1024 位，並將遞增長度傳回為 64 位，則有效的密鑰長度為 512、576、640,... 1024. |
|
CSP 的名稱，格式為 Null 終止 的 CHAR 字串。 此字串與 CryptAcquireContext 函式之 pszProvider 參數中傳遞的字串相同，以指定要使用的目前 CSP。 |
|
指出 CSP 提供者類型的 DWORD 值。 |
|
取得智慧卡的跟證書存儲。 此證書存儲包含儲存在智慧卡上的所有跟證書。
pbData 參數是接收證書存儲句柄的 HCERTSTORE 變數位址。 當不再需要此句柄時，呼叫端必須使用 CertCloseStore 函式將其關閉。 Windows Server 2003 和 Windows XP： 不支援此參數。 |
|
會話金鑰的大小，以位為單位。 |
|
與 伺服器閘道密碼編譯搭配使用。 |
|
AT_SIGNATURE遞增長度的位數。 這項資訊會與PP_ENUMALGS_EX值中傳回的資訊搭配使用。 使用 PP_ENUMALGS_EX 和 PP_SIG_KEYSIZE_INC 時傳回的資訊，即可判斷AT_SIGNATURE的有效 密鑰長度 。 然後，這些密鑰長度可以與 CryptGenKey 搭配使用。
例如，如果 CSP 列舉 CALG_RSA_SIGN (AT_SIGNATURE) 最小 密鑰長度 為 512 位，且最大為 1024 位，並將遞增長度傳回為 64 位，則有效的密鑰長度為 512、576、640,... 1024. |
|
指定金鑰簽章 PIN 包含在 pbData 中。 PIN 會以 Null 終止的 ASCII 字串表示。 |
|
取得智慧卡的標識碼。 pbData 參數是接收智慧卡識別碼之 GUID 結構的位址。
Windows Server 2003 和 Windows XP： 不支援此參數。 |
|
取得智慧卡卡片閱讀機的名稱。 pbData 參數是 ANSI 字元陣列的位址，會接收以 Null 結尾的 ANSI 字串，其中包含智慧卡讀取器的名稱。 這個緩衝區的大小，包含在 pdwDataLen 參數所指向的變數中，必須包含 NULL 終止符。
Windows Server 2003 和 Windows XP： 不支援此參數。 |
|
對稱金鑰的大小。 |
|
不會使用此查詢。 |
|
目前密鑰容器的唯一容器名稱，格式為 Null 終止 的 CHAR 字串。 對於許多 CSP，使用 PP_CONTAINER 值時，此名稱會傳回相同的名稱。 CryptAcquireContext 函式必須使用此容器名稱。 |
|
指出是否支援硬體隨機數產生器 (RNG) 。 指定 PP_USE_HARDWARE_RNG 時，如果支持硬體 RNG，函式會成功並傳回 TRUE 。 如果不支援硬體 RNG，此函式會失敗並傳回 FALSE 。 如果支援 RNG，可以在 CryptSetProvParam 中設定PP_USE_HARDWARE_RNG，以指出 CSP 必須獨佔使用此提供者內容的硬體 RNG。 使用 PP_USE_HARDWARE_RNG 時， pbData 參數必須是 NULL ， 而 dwFlags 必須是零。
目前不支援使用硬體 RNG 的 Microsoft CSP。 |
|
取得智慧卡的使用者證書存儲。 此證書存儲包含儲存在智慧卡上的所有用戶憑證。 此存放區中的憑證會使用PKCS_7_ASN_ENCODING或X509_ASN_ENCODING編碼進行編碼，而且應該包含 CERT_KEY_PROV_INFO_PROP_ID 屬性。
pbData 參數是 HCERTSTORE 變數的位址，可接收記憶體內部證書存儲的句柄。 當不再需要此句柄時，呼叫端必須使用 CertCloseStore 函式將其關閉。 Windows Server 2003 和 Windows XP： 不支援此參數。 |
|
CSP 版本號碼。 最小有效位元組包含次要版本號碼，以及下一個最重要的位元組主要版本號碼。 2.0 版會以0x00000200表示。 為了維持與舊版 Microsoft 基礎密碼編譯提供者 和 Microsoft 增強式密碼編譯提供者的回溯相容性，提供者名稱會保留更新版本中的 “v1.0” 指定。 |
[out] pbData
要接收數據的緩衝區指標。 此數據的形式會根據 dwParam 的值而有所不同。 當 dwParam 設定為 PP_USE_HARDWARE_RNG 時， pbData 必須設定為 NULL。
此參數可以是 NULL ，可設定此資訊的大小以供記憶體配置之用。 如需詳細資訊，請參閱 擷取未知長度的數據。
[in, out] pdwDataLen
DWORD 值的指標，指定 pbData 參數所指向之緩衝區的大小，以位元組為單位。 當函式傳回時， DWORD 值會包含儲存或儲存在緩衝區中的位元元組數目。
如果已設定PP_ENUMALGS或 PP_ENUMALGS_EX，pdwDataLen 參數的運作方式會稍有不同。 如果 pbData 為 NULL ，或 pdwDataLen 所指向的值太小，則此參數中傳回的值是列舉清單中的最大專案大小，而不是目前讀取的專案大小。
如果已設定PP_ENUMCONTAINERS，則第一次呼叫函式會傳回目前提供者所允許的密鑰容器上限大小。 這與其他可能的行為相反，例如傳回最長現有容器的長度或目前容器的長度。 後續列舉呼叫不會變更 dwLen 參數。 針對每個列舉容器，呼叫端可以視需要，以程式設計方式判斷 以 Null 終止字串的長度。 如果讀取其中一個列舉值，且 pbData 參數為 NULL，則必須指定CRYPT_FIRST旗標，才能正確擷取大小資訊。
[in] dwFlags
如果 dwParam是PP_KEYSET_SEC_DESCR，則會擷取儲存密鑰的金鑰容器上的安全性描述元。 在此案例中， dwFlags 用來傳入 SECURITY_INFORMATION 位旗標，指出要求的安全性資訊，如平臺 SDK 中所定義。 SECURITY_INFORMATION 位旗標可以與位OR 運算結合。
定義下列值以搭配 PP_KEYSET_SEC_DESCR使用。
| 值 | 意義 |
|---|---|
|
正在參考對象的擁有者標識碼。 |
|
正在參考物件的主要群組標識碼。 |
|
正在參考物件的任意 ACL。 |
|
正在參考對象的系統 ACL。 |
定義下列值以搭配 PP_ENUMALGS、 PP_ENUMALGS_EX和 PP_ENUMCONTAINERS使用。
| 值 | 意義 |
|---|---|
|
擷取列舉中的第一個專案。 這與重設列舉值的效果相同。 |
|
擷取列舉中的下一個專案。 當沒有其他要擷取的專案時，此函式將會失敗，並將最後一個錯誤設定為 ERROR_NO_MORE_ITEMS。 |
|
擷取已啟用 SGC) 憑證 的伺服器閘道加密 (。 不再支援已啟用 SGC 的憑證。 |
|
未使用此旗標。 |
|
未使用此旗標。 |
傳回值
如果函式成功，則傳回值為非零 (TRUE) 。
如果函式失敗，則傳回值為零， (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError。
NTE 前面出現的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。
| 傳回碼 | Description |
|---|---|
|
其中一個參數指定無效的句柄。 |
|
其中一個參數包含無效的值。 這通常是無效的指標。 |
|
如果 pbData 參數指定的緩衝區不足以保存傳回的數據，函式會設定ERROR_MORE_DATA程序代碼，並以位元組為單位儲存 pdwDataLen 所指向的變數中所需的緩衝區大小。 |
|
已到達列舉清單的結尾。 pbData 緩衝區中沒有有效的數據。 只有在 dwParam 等於 PP_ENUMALGS 或 PP_ENUMCONTAINERS 時，才會傳回此錯誤碼。 |
|
dwFlags 參數會指定無效的旗標。 |
|
dwParam 參數會指定未知的值編號。 |
|
hProv 指定的 CSP 內容無效。 |
備註
此函式不得用於多線程程序的線程上。
如果 dwParam 是PP_IMPTYPE，則會在 pbData 中傳回下列值。
| 值 | 意義 |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
實作位於硬體中。 |
| CRYPT_IMPL_SOFTWARE 0x02 |
實作位於軟體中。 |
| CRYPT_IMPL_MIXED 0x03 |
實作牽涉到硬體和軟體。 |
| CRYPT_IMPL_UNKNOWN 0x04 |
實作類型未知。 |
| CRYPT_IMPL_REMOVABLE 0x08 |
實作位於卸除式媒體中。 |
dwFlags 參數可用來傳入指出要求安全性資訊的SECURITY_INFORMATION位旗標。 安全性描述元的指標會在 pbData 參數中傳回，而安全性描述元的長度則會在 pdwDataLen 參數中傳回。 密鑰容器安全性是使用 SetFileSecurity 和 GetFileSecurity 來處理。
您可以將 dwParam 設定為 PP_ENUMALGS 或 PP_ENUMALGS_EX 所列舉的演算法類別。 這可能是為了顯示支援的加密演算法清單，並忽略其餘部分。 GET_ALG_CLASS (x) 宏會採用演算法識別碼作為自變數，並傳回程式代碼，指出該演算法的一般類別。 可能的傳回值包括：
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
下表列出 Microsoft 基底密碼編譯提供者所支援的演算法，以及每個演算法的類別。
| 名稱 | 識別碼 | 類別 |
|---|---|---|
| “MD2” | CALG_MD2 | ALG_CLASS_HASH |
| “MD5” | CALG_MD5 | ALG_CLASS_HASH |
| “SHA” | CALG_SHA | ALG_CLASS_HASH |
| “MAC” | CALG_MAC | ALG_CLASS_HASH |
| “RSA_SIGN” | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| “RSA_KEYX” | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| “RC2” | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| “RC4” | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
應用程式不得使用演算法與無法辨識的演算法標識碼。 使用未知的密碼編譯演算法可能會產生無法預期的結果。
範例
下列範例顯示尋找與密碼編譯服務提供者句柄相關聯的 CSP 名稱，以及與句柄相關聯的密鑰容器名稱。 如需此範例的完整內容，請參閱 範例 C 程式：使用 CryptAcquireContext。
如需使用此函式的另一個範例，請參閱 範例 C 程式：列舉 CSP 提供者和提供者類型。
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
規格需求
| 需求 | 值 |
|---|---|
| 最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
| 最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
| 目標平台 | Windows |
| 標頭 | wincrypt.h |
| 程式庫 | Advapi32.lib |
| Dll | Advapi32.dll |