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
查询的性质。 定义了以下查询。
| 值 | 含义 |
|---|---|
|
以 LPSTR 的形式返回 pbData 参数中的管理员个人标识号 (PIN) 。 |
|
不使用此常量。 |
|
不使用此常量。 |
|
返回与 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 成员。 |
|
不使用此常量。 |
|
一个 DWORD 值，该值指示 CSP 的实现方式。 有关可能值的表，请参阅备注。 |
|
未使用此查询。 |
|
指定密钥交换 PIN 包含在 pbData 中。 PIN 表示为 以 null 结尾的 ASCII 字符串。 |
|
检索密钥存储容器 的安全描述符 。 pbData 参数是接收密钥存储容器的安全描述符的SECURITY_DESCRIPTOR结构的地址。 安全描述符以自相对格式返回。 |
|
确定 hProv 参数是否是计算机密钥集。 pbData 参数必须是 DWORD;如果该标志传递给 CryptAcquireContext 函数，则 DWORD 将设置为 CRYPT_MACHINE_KEYSET 标志。 |
|
返回有关 CSP 支持的密钥说明符值的信息。 键说明符值在逻辑 OR 中联接，并在调用的 pbData 参数中作为 DWORD 返回。 例如，Microsoft 基本加密提供程序版本 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 枚举最小密钥长度为 512 位、最大为 1024 位的 CALG_RSA_KEYX (AT_KEYEXCHANGE) ，并将增量长度返回为 64 位，则有效密钥长度为 512、576、640,... 1024. |
|
以 null 结尾的 CHAR 字符串形式的 CSP 的名称。 此字符串与在 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 枚举最小密钥长度为 512 位、最大为 1024 位的CALG_RSA_SIGN (AT_SIGNATURE) ，并将增量长度返回为 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 必须为零。
目前没有 Microsoft CSP 支持使用硬件 RNG。 |
|
获取智能卡的用户证书存储。 此证书存储区包含存储在智能卡上的所有用户证书。 此存储中的证书使用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
如果 dwParamPP_KEYSET_SEC_DESCR，则会检索存储密钥的密钥容器上的安全描述符。 对于这种情况， dwFlags 用于传入指示平台 SDK 中定义的 SECURITY_INFORMATION 位标志，这些标志指示请求的安全信息。 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 生成。 下面是一些可能的错误代码。
| 返回代码 | 说明 |
|---|---|
|
其中一个参数指定无效的句柄。 |
|
其中一个参数包含无效的值。 这通常是无效的指针。 |
|
如果 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 |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |