CryptSetProvParam 函式 (wincrypt.h)

重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。
 
CryptSetProvParam 函式會自定義密碼編譯服務提供者的作業, (CSP) 。 此函式通常用於在與 CSP 相關聯的金鑰容器上設定安全性描述元,以控制該金鑰容器中私鑰的存取。

語法

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

參數

[in] hProv

要為其設定值的 CSP 句柄。 此句柄必須使用 CryptAcquireContext 函式來建立。

[in] dwParam

指定要設定的參數。 這可以是下列其中一個值。

意義
PP_CLIENT_HWND
1 (0x1)
設定提供者用來做為其建立之任何對話框父代的視窗句柄。 pbData 包含 HWND 的指標,其中包含父視窗句柄。

呼叫 CryptAcquireContext 之前,必須先設定此參數,因為呼叫 CryptAcquireContext 時,許多 CSP 都會顯示使用者介面。 您可以傳遞 hProv 參數的 NULL,以針對後續在此進程內取得的所有密碼編譯內容設定此視窗句柄。

PP_DELETEKEY
24 (0x18)
刪除與 哈希加密或驗證內容相關聯的暫時金鑰。 這會釋放記憶體,並清除與機碼相關聯的登錄設定。
PP_KEYEXCHANGE_ALG
未使用這個常數。
PP_KEYEXCHANGE_PIN
32 (0x20)
指定金鑰交換 PIN 包含在 pbData 中。 PIN 會以 Null 終止的 ASCII 字串表示。
PP_KEYEXCHANGE_KEYSIZE
未使用這個常數。
PP_KEYSET_SEC_DESCR
8 (0x8)
在金鑰記憶體容器上設定 安全性描述元pbData 參數是SECURITY_DESCRIPTOR結構的位址,其中包含密鑰記憶體容器的新安全性描述元。
PP_PIN_PROMPT_STRING
44 (0x2C)
設定在要求使用者 PIN 時向用戶顯示的替代提示字串。 pbData 參數是 Null 終止 Unicode 字串的指標。
PP_ROOT_CERTSTORE
46 (0x2E)
設定智慧卡的跟證書存儲。 提供者會將跟證書從此存放區複製到智慧卡。

pbData 參數是 HCERTSTORE 變數,其中包含新證書存儲的句柄。 提供者會在此呼叫期間從存放區複製憑證,因此呼叫此函式之後,安全關閉此存放區。

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

PP_SIGNATURE_ALG
未使用這個常數。
PP_SIGNATURE_PIN
33 (0x21)
指定簽章 PIN。 pbData 參數是代表 PIN 的 Null 終止 ASCII 字串。
PP_SIGNATURE_KEYSIZE
未使用這個常數。
PP_UI_PROMPT
21 (0x15)
針對智慧卡提供者,將顯示給使用者的搜尋字串設定為插入智慧卡的提示。 此字串會傳遞為傳遞至 SCardUIDlgSelectCard 函式之 OPENCARDNAME_EX 結構的 lpstrSearchDesc 成員。 此字串用於呼叫進程的存留期。

pbData 參數是 Null 終止 Unicode 字串的指標。

PP_USE_HARDWARE_RNG
38 (0x26)
指定 CSP 必須獨佔使用硬體隨機數產生器, (RNG) 。 設定 PP_USE_HARDWARE_RNG 時,隨機值會以獨佔方式從硬體 RNG 取得,而且不會使用其他來源。 如果 CSP 支援硬體 RNG,而且可以獨佔使用,則函式會成功並傳回 TRUE;否則,函式會失敗並傳回 FALSEpbData 參數必須是 NULL,而且使用此值時 dwFlags 必須為零。

目前沒有任何 Microsoft CSP 支援使用硬體 RNG。

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_SECURE_KEYEXCHANGE_PIN
47 (0x2F)
指定已加密的金鑰交換 PIN 包含在 pbData 中。 pbData 參數包含DATA_BLOB
PP_SECURE_SIGNATURE_PIN
48 (0x30)
指定已加密的簽章 PIN 包含在 pbData 中。 pbData 參數包含DATA_BLOB
PP_SMARTCARD_READER
43 (0x2B)
指定智慧卡閱讀機的名稱。 pbData 參數是 ANSI 字元陣列的位址,其中包含包含智慧卡讀取器名稱的 Null 終止 ANSI 字串。

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

PP_SMARTCARD_GUID
45 (0x2D)
指定智慧卡的識別碼。 pbData 參數是包含智慧卡識別碼的 GUID 結構位址。

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

[in] pbData

數據緩衝區的指標,其中包含要設定為提供者參數的值。 此數據的形式會根據 dwParam 值而有所不同。 如果 dwParam 包含 PP_USE_HARDWARE_RNG,此參數必須是 NULL

[in] dwFlags

如果 dwParam 包含PP_KEYSET_SEC_DESCR,dwFlags 會包含SECURITY_INFORMATION適用的位旗標,如平臺 SDK 中所定義。 密鑰容器安全性是使用 SetFileSecurityGetFileSecurity 來處理。

您可以使用位 OR 運算來結合這些位旗標。 如需詳細資訊,請參閱 CryptGetProvParam

如果 dwParam是PP_USE_HARDWARE_RNGPP_DELETEKEY,dwFlags 必須設定為零。

傳回值

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

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

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

傳回碼 Description
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
函式會以非預期的方式失敗。

規格需求

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

另請參閱

CryptAcquireContext

CryptGetProvParam

CryptSetKeyParam

服務提供者函式