CryptSetProvParam 函数 (wincrypt.h)

项目
03/13/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 之前必须设置此参数，因为许多 CSP 在调用 CryptAcquireContext 时将显示用户界面。可以为 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 参数是一个以 null 结尾的 ASCII 字符串，表示 PIN。
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)	指定 pbData 中包含加密密钥交换 PIN。 pbData 参数包含DATA_BLOB。
PP_SECURE_SIGNATURE_PIN 48 (0x30)	指定 pbData 中包含加密签名 PIN。 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 将包含平台 SDK 中定义的 SECURITY_INFORMATION 适用的位标志。密钥容器安全性使用 SetFileSecurity 和 GetFileSecurity 进行处理。

这些位标志可以通过使用按位 OR 运算进行组合。有关详细信息，请参阅 CryptGetProvParam。

如果 dwParam是PP_USE_HARDWARE_RNG 或 PP_DELETEKEY，则必须将 dwFlags 设置为零。

返回值

如果函数成功，则返回值为非零 (TRUE) 。

如果函数失败，则返回值为零， (FALSE) 。有关扩展的错误信息，请调用 GetLastError。

“NTE”开头的错误代码由使用的特定 CSP 生成。错误代码包括以下内容。

返回代码	说明
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
Library	Advapi32.lib
DLL	Advapi32.dll

另请参阅

CryptSetProvParam 函数 (wincrypt.h)

语法

参数

返回值

要求

另请参阅

反馈

反馈

其他资源