CryptSetProvParam 函式 (wincrypt.h)

發行項
03/09/2024

重要此 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;否則，函式會失敗並傳回 FALSE。 pbData 參數必須是 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 中所定義。密鑰容器安全性是使用 SetFileSecurity 和 GetFileSecurity 來處理。

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

如果 dwParam是PP_USE_HARDWARE_RNG或PP_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

另請參閱

共用方式為

CryptSetProvParam 函式 (wincrypt.h)

語法

參數

傳回值

規格需求

另請參閱

意見反應

其他資源