共用方式為


CryptGetProvParam 函式 (wincrypt.h)

重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。
 
CryptGetProvParam 函式會擷取管理密碼編譯服務提供者作業的參數, (CSP) 。

語法

BOOL CryptGetProvParam(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

參數

[in] hProv

查詢 CSP 目標的句柄。 必須使用 CryptAcquireContext 函式來建立此句柄。

[in] dwParam

查詢的本質。 已定義下列查詢。

意義
PP_ADMIN_PIN
31 (0x1F)
pbData 參數中的系統管理員個人識別碼 (PIN) 傳回為 LPSTR
PP_APPLI_CERT
18 (0x12)
不會使用這個常數。
PP_CHANGE_PASSWORD
7 (0x7)
不會使用這個常數。
PP_CERTCHAIN
9 (0x9)
傳回與 hProv 句柄相關聯的憑證鏈結。 傳回的憑證鏈結 X509_ASN_ENCODING 編碼。
PP_CONTAINER
6 (0x6)
目前 密鑰容器 的名稱,做為 以 Null 結尾的 CHAR 字串。 此字串與 CryptAcquireContext 函式之 pszContainer 參數中傳遞的字串完全相同,以指定要使用的密鑰容器。 您可以讀取 pszContainer 參數來判斷預設金鑰容器的名稱。
PP_CRYPT_COUNT_KEY_USE
41 (0x29)
Microsoft CSP 未實作。 此行為可由其他 CSP 實作。

Windowsxp: 不支援此參數。

PP_ENUMALGS
1 (0x1)
PROV_ENUMALGS結構,其中包含所查詢 CSP 所支援之一種演算法的相關信息。

第一次讀取此值時, dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著,您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標,以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時,已達到列舉的結尾。

此函式不是安全線程,而且如果此函式用於多線程內容,則可能無法列舉所有可用的演算法。

PP_ENUMALGS_EX
22 (0x16)
PROV_ENUMALGS_EX結構,其中包含所查詢 CSP 所支援之一種演算法的相關信息。 傳回的結構包含演算法的詳細資訊,而不是針對PP_ENUMALGS傳回的結構。

第一次讀取此值時, dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著,您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標,以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時,已達到列舉的結尾。

如果此函式用於多線程內容,則此函式不是安全線程,而且如果此函式用於多線程內容,則可能無法列舉所有可用的演算法。

PP_ENUMCONTAINERS
2 (0x2)
CSP 所維護的其中一個密鑰容器名稱,格式為 Null 終止 的 CHAR 字串。

第一次讀取此值時, dwFlags 參數必須包含 CRYPT_FIRST 旗標。 這樣做會導致此函式擷取列舉中的第一個專案。 接著,您可以在 dwFlags 參數中設定 CRYPT_NEXT 旗標,以擷取後續專案。 當此函式失敗 並出現ERROR_NO_MORE_ITEMS 錯誤碼時,已達到列舉的結尾。

若要列舉與計算機相關聯的密鑰容器,請先使用 CRYPT_MACHINE_KEYSET 旗標呼叫 CryptAcquireContext,然後使用 CryptAcquireContext 傳回的句柄做為 CryptGetProvParam 呼叫中的 hProv 參數。

如果此函式用於多線程內容,則此函式不是安全線程,而且如果此函式用於多線程內容,則可能無法列舉所有可用的演算法。

PP_ENUMELECTROOTS
26 (0x1A)
不會使用這個常數。
PP_ENUMEX_SIGNING_PROT
40 (0x28)
表示目前的 CSP 支援PROV_ENUMALGS_EX結構的 dwProtocols 成員。 如果此函式成功,CSP 支援PROV_ENUMALGS_EX結構的 dwProtocols 成員。 如果此函式失敗並出現 NTE_BAD_TYPE 錯誤碼,CSP 不支援 dwProtocols 成員。
PP_ENUMMANDROOTS
25 (0x19)
不會使用這個常數。
PP_IMPTYPE
3 (0x3)
指出 CSP 實作方式的 DWORD 值。 如需可能值的數據表,請參閱。
PP_KEY_TYPE_SUBTYPE
10 (0xA)
不會使用此查詢。
PP_KEYEXCHANGE_PIN
32 (0x20)
指定金鑰交換 PIN 包含在 pbData 中。 PIN 會以 Null 終止的 ASCII 字串表示。
PP_KEYSET_SEC_DESCR
8 (0x8)
擷取金鑰記憶體容器 的安全性描述項pbData 參數是接收密鑰記憶體容器安全性描述項之SECURITY_DESCRIPTOR結構的位址。 安全性描述項會以自我相對格式傳回。
PP_KEYSET_TYPE
27 (0x1B)
判斷 hProv 參數是否為計算機金鑰集。 pbData 參數必須是 DWORD;如果該旗標傳遞至 CryptAcquireContext 函式,DWORD 將會設定為 CRYPT_MACHINE_KEYSET 旗標。
PP_KEYSPEC
39 (0x27)
傳回 CSP 所支援之金鑰規範值的相關信息。 索引鍵規範值會聯結在邏輯 OR 中,並在呼叫的 pbData 參數中以 DWORD 傳回。 例如,Microsoft Base Cryptographic Provider 1.0 版會傳回 DWORD 值 AT_SIGNATURE |AT_KEYEXCHANGE。
PP_KEYSTORAGE
17 (0x11)
傳回 CRYPT_SEC_DESCR的 DWORD 值。
PP_KEYX_KEYSIZE_INC
35 (0x23)
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.
PP_NAME
4 (0x4)
CSP 的名稱,格式為 Null 終止 的 CHAR 字串。 此字串與 CryptAcquireContext 函式之 pszProvider 參數中傳遞的字串相同,以指定要使用的目前 CSP。
PP_PROVTYPE
16 (0x10)
指出 CSP 提供者類型的 DWORD 值。
PP_ROOT_CERTSTORE
46 (0x2E)
取得智慧卡的跟證書存儲。 此證書存儲包含儲存在智慧卡上的所有跟證書。

pbData 參數是接收證書存儲句柄的 HCERTSTORE 變數位址。 當不再需要此句柄時,呼叫端必須使用 CertCloseStore 函式將其關閉。

Windows Server 2003 和 Windows XP: 不支援此參數。

PP_SESSION_KEYSIZE
20 (0x14)
會話金鑰的大小,以位為單位。
PP_SGC_INFO
37 (0x25)
伺服器閘道密碼編譯搭配使用
PP_SIG_KEYSIZE_INC
34 (0x22)
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.

PP_SIGNATURE_PIN
33 (0x21)
指定金鑰簽章 PIN 包含在 pbData 中。 PIN 會以 Null 終止的 ASCII 字串表示。
PP_SMARTCARD_GUID
45 (0x2D)
取得智慧卡的標識碼。 pbData 參數是接收智慧卡識別碼之 GUID 結構的位址。

Windows Server 2003 和 Windows XP: 不支援此參數。

PP_SMARTCARD_READER
43 (0x2B)
取得智慧卡卡片閱讀機的名稱。 pbData 參數是 ANSI 字元陣列的位址,會接收以 Null 結尾的 ANSI 字串,其中包含智慧卡讀取器的名稱。 這個緩衝區的大小,包含在 pdwDataLen 參數所指向的變數中,必須包含 NULL 終止符。

Windows Server 2003 和 Windows XP: 不支援此參數。

PP_SYM_KEYSIZE
19 (0x13)
對稱金鑰的大小。
PP_UI_PROMPT
21 (0x15)
不會使用此查詢。
PP_UNIQUE_CONTAINER
36 (0x24)
目前密鑰容器的唯一容器名稱,格式為 Null 終止 的 CHAR 字串。 對於許多 CSP,使用 PP_CONTAINER 值時,此名稱會傳回相同的名稱。 CryptAcquireContext 函式必須使用此容器名稱。
PP_USE_HARDWARE_RNG
38 (0x26)
指出是否支援硬體隨機數產生器 (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。

PP_USER_CERTSTORE
42 (0x2A)
取得智慧卡的使用者證書存儲。 此證書存儲包含儲存在智慧卡上的所有用戶憑證。 此存放區中的憑證會使用PKCS_7_ASN_ENCODING或X509_ASN_ENCODING編碼進行編碼,而且應該包含 CERT_KEY_PROV_INFO_PROP_ID 屬性。

pbData 參數是 HCERTSTORE 變數的位址,可接收記憶體內部證書存儲的句柄。 當不再需要此句柄時,呼叫端必須使用 CertCloseStore 函式將其關閉。

Windows Server 2003 和 Windows XP: 不支援此參數。

PP_VERSION
5 (0x5)
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 值會包含儲存或儲存在緩衝區中的位元元組數目。

注意 處理緩衝區中傳回的數據時,應用程式必須使用傳回的數據實際大小。 實際大小可能會稍微小於輸入中指定的緩衝區大小。 (輸入時,通常會指定足夠的緩衝區大小,以確保最大的可能輸出數據符合 buffer。) On 輸出中,此參數所指向的變數會更新,以反映複製到緩衝區的實際數據大小。

如果已設定PP_ENUMALGS或 PP_ENUMALGS_EX,pdwDataLen 參數的運作方式會稍有不同。 如果 pbDataNULL ,或 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使用。

意義
OWNER_SECURITY_INFORMATION
正在參考對象的擁有者標識碼。
GROUP_SECURITY_INFORMATION
正在參考物件的主要群組標識碼。
DACL_SECURITY_INFORMATION
正在參考物件的任意 ACL。
SACL_SECURITY_INFORMATION
正在參考對象的系統 ACL。
 

定義下列值以搭配 PP_ENUMALGSPP_ENUMALGS_EXPP_ENUMCONTAINERS使用。

意義
CRYPT_FIRST
1 (0x1)
擷取列舉中的第一個專案。 這與重設列舉值的效果相同。
CRYPT_NEXT
2 (0x2)
擷取列舉中的下一個專案。 當沒有其他要擷取的專案時,此函式將會失敗,並將最後一個錯誤設定為 ERROR_NO_MORE_ITEMS
CRYPT_SGC_ENUM
4 (0x4)
擷取已啟用 SGC) 憑證 的伺服器閘道加密 (。 不再支援已啟用 SGC 的憑證。
CRYPT_SGC
未使用此旗標。
CRYPT_FASTSGC
未使用此旗標。

傳回值

如果函式成功,則傳回值為非零 (TRUE) 。

如果函式失敗,則傳回值為零, (FALSE) 。 如需擴充錯誤資訊,請呼叫 GetLastError

NTE 前面出現的錯誤碼是由所使用的特定 CSP 所產生。 以下是一些可能的錯誤碼。

傳回碼 Description
ERROR_INVALID_HANDLE
其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER
其中一個參數包含無效的值。 這通常是無效的指標。
ERROR_MORE_DATA
如果 pbData 參數指定的緩衝區不足以保存傳回的數據,函式會設定ERROR_MORE_DATA程序代碼,並以位元組為單位儲存 pdwDataLen 所指向的變數中所需的緩衝區大小。
ERROR_NO_MORE_ITEMS
已到達列舉清單的結尾。 pbData 緩衝區中沒有有效的數據。 只有在 dwParam 等於 PP_ENUMALGS 或 PP_ENUMCONTAINERS 時,才會傳回此錯誤碼。
NTE_BAD_FLAGS
dwFlags 參數會指定無效的旗標。
NTE_BAD_TYPE
dwParam 參數會指定未知的值編號。
NTE_BAD_UID
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 參數中傳回。 密鑰容器安全性是使用 SetFileSecurityGetFileSecurity 來處理。

您可以將 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

另請參閱

絕對和 Self-Relative 安全性描述元

CryptAcquireContext

CryptCreateHash

CryptDeriveKey

CryptGenKey

CryptGetKeyParam

CryptSetProvParam

服務提供者函式