CertFindCertificateInStore 函数 （wincrypt.h）
语法
PCCERT_CONTEXT CertFindCertificateInStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwCertEncodingType,
[in] DWORD dwFindFlags,
[in] DWORD dwFindType,
[in] const void *pvFindPara,
[in] PCCERT_CONTEXT pPrevCertContext
);
参数
[in] hCertStore
要搜索
[in] dwCertEncodingType
指定使用的编码类型。 证书和 消息编码类型 都必须通过将它们与按位OR 操作组合在一起，如以下示例所示：
X509_ASN_ENCODING |PKCS_7_ASN_ENCODING当前定义的编码类型为：
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] dwFindFlags
与某些 dwFindType 值一起使用以修改搜索条件。 对于大多数 dwFindType 值，不使用 dwFindFlags，应设置为零。 有关详细信息，请参阅“备注”。
[in] dwFindType
指定要进行的搜索的类型。 搜索类型确定数据类型、内容和使用 pvFindPara。 此参数可以是下列值之一。
| 价值 | 意义 |
|---|---|
|
未使用搜索条件。 返回存储中的下一个证书。
注意 可能无法在存储区中保留证书上下文的顺序。
若要访问特定证书，必须循环访问存储中的证书。
|
|
pvFindPara的数据类型：CERT_ID 结构。
查找由指定 CERT_ID标识的证书。 |
|
pvFindPara的数据类型：CTL_USAGE 结构。
搜索具有szOID_ENHANCED_KEY_USAGE扩展或CERT_CTL_PROP_ID的证书，该证书与 |
|
pvFindPara的数据类型：CERT_ENHKEY_USAGE 结构。
在存储中搜索具有 增强密钥用法的证书 扩展或增强的密钥使用属性，以及与 CERT_ENHKEY_USAGE 结构中的 cUsageIdentifier 成员匹配的使用标识符。 如果证书具有 CERT_EXTENSION结构且 pszObjId 成员设置为szOID_ENHANCED_KEY_USAGE，则证书具有增强的密钥使用扩展。 如果设置了证书CERT_ENHKEY_USAGE_PROP_ID标识符，则证书具有增强的密钥使用属性。 如果在 dwFindFlags中设置CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG，则不使用密钥用法扩展或属性的证书也匹配。 设置此标志优先于在 pvFindPara中传递 NULL。 如果设置了CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG，则仅对密钥使用扩展执行匹配。 有关对搜索条件的标志修改的信息，请参阅“备注”。 |
|
pvFindPara的数据类型：CERT_CONTEXT 结构。
搜索与指定证书上下文完全匹配的证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
使用与 CRYPT_HASH_BLOB 结构中的哈希匹配的 SHA1 哈希搜索证书。 |
|
搜索具有私钥的证书。 密钥可以是临时密钥，也可以保存在磁盘上。 密钥可以是旧加密 API （CAPI） 密钥或 CNG 密钥。
注意 可能无法在存储区中保留证书上下文的顺序。 因此，若要访问特定证书，必须循环访问所有证书。
|
|
pvFindPara的数据类型：CERT_RDN 结构。
搜索具有与 CERT_RDN 结构中的属性匹配的指定颁发者属性的证书。 如果设置了这些值，该函数会将证书中的颁发者属性与此 CERT_RDN 结构中 CERT_RDN_ATTR 数组的元素进行比较。 比较循环访问查找与证书颁发者属性匹配的 CERT_RDN_ATTR 属性。 如果 CERT_RDN_ATTR 的 pszObjId 成员 NULL，则忽略属性对象标识符。 如果CERT_RDN_ANY_TYPE dwValueTypeCERT_RDN_ATTR 成员，则忽略值类型。 如果 CERT_RDN_VALUE_BLOB 的 pbData 成员 NULL，则任何值都是匹配项。 目前仅支持完全区分大小写的匹配。 有关 Unicode 选项的信息，请参阅“备注”。 设置这些值时，搜索仅限于编码类型与 dwCertEncodingType 匹配的证书。 |
|
pvFindPara的数据类型：CERT_NAME_BLOB 结构。
搜索与 CERT_NAME_BLOB 中名称的整个颁发者名称完全匹配的证书。搜索仅限于与 dwCertEncodingType匹配的证书。 |
|
pvFindPara的数据类型：CERT_CONTEXT 结构。
在 CERT_CONTEXT中搜索具有与颁发者匹配的使用者的证书。 使用 CertGetCertificateChain 函数，而不是将 CertFindCertificateInStore 与此值配合使用。 |
|
pvFindPara的数据类型：以 Null 结尾的 Unicode 字符串。
搜索包含指定颁发者名称字符串的证书。 证书的颁发者成员使用格式设置为CERT_SIMPLE_NAME_STR格式的 CertNameToStr 转换为适当类型的名称字符串。 然后执行不区分大小写的子字符串内字符串匹配。 设置此值后，搜索仅限于编码类型与 dwCertEncodingType匹配 如果子字符串匹配失败，并且主题包含具有 Punycode 编码字符串的电子邮件 RDN，则 CERT_NAME_STR_ENABLE_PUNYCODE_FLAG 用于将主题转换为 Unicode 字符串，并再次执行子字符串匹配。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
使用与 CRYPT_HASH_BLOB中的密钥标识符匹配的CERT_KEY_IDENTIFIER_PROP_ID属性搜索证书。 |
|
pvFindPara的数据类型：包含键规范的 DWORD 变量。
搜索CERT_KEY_SPEC_PROP_ID属性与 pvFindPara中的密钥规范匹配的证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
搜索与 CRYPT_HASH_BLOB中的哈希匹配的 MD5 哈希的证书。 |
|
pvFindPara的数据类型：包含属性标识符的 DWORD 变量。
在 pvFindPara中搜索与由 DWORD 值指定的属性标识符匹配的证书。 |
|
pvFindPara的数据类型：CERT_PUBLIC_KEY_INFO 结构。
使用与 CERT_PUBLIC_KEY_INFO 结构中的公钥匹配的公钥搜索证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
使用与 CRYPT_HASH_BLOB 结构中的哈希匹配的 SHA1 哈希搜索证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
搜索具有 SHA1 + SHA256 哈希的证书，该哈希与 CRYPT_HASH_BLOB 结构中的哈希匹配。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
搜索具有与 CRYPT_HASH_BLOB 结构中的哈希匹配的 SHA256 哈希的证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
搜索具有与 CRYPT_HASH_BLOB 结构中的签名哈希匹配的签名哈希的证书。 |
|
pvFindPara的数据类型：CERT_RDN 结构。
搜索具有与 CERT_RDN 结构中的属性匹配的指定使用者属性的证书。 如果设置了 RDN 值，该函数会将证书中使用者的属性与此 CERT_RDN 结构中 CERT_RDN_ATTR 数组的元素进行比较。 比较循环访问查找与证书使用者属性匹配的 CERT_RDN_ATTR 属性。 如果 CERT_RDN_ATTR 的 pszObjId 成员 NULL，则忽略属性对象标识符。 如果CERT_RDN_ANY_TYPE dwValueTypeCERT_RDN_ATTR 成员，则忽略值类型。 如果 CERT_RDN_VALUE_BLOB 的 pbData 成员 NULL，则任何值都是匹配项。 目前仅支持完全区分大小写的匹配。 有关 Unicode 选项的信息，请参阅“备注”。 设置这些值时，搜索仅限于编码类型与 dwCertEncodingType 匹配的证书。 |
|
pvFindPara的数据类型：CERT_INFO 结构。
搜索具有颁发者的证书和与 CERT_INFO 结构中的颁发者和序列号匹配的序列号。 |
|
pvFindPara的数据类型：CERT_NAME_BLOB 结构。
搜索与 CERT_NAME_BLOB 结构中名称完全匹配的整个使用者名称的证书。 搜索仅限于与 dwCertEncodingType的值匹配的证书。 |
|
pvFindPara的数据类型：以 Null 结尾的 Unicode 字符串。
搜索包含指定使用者名称字符串的证书。 证书的主题成员使用格式为 CERT_SIMPLE_NAME_STR 的 CertNameToStr 格式转换为适当类型的名称字符串。 然后执行不区分大小写的子字符串内字符串匹配。 设置此值后，搜索仅限于编码类型与 dwCertEncodingType匹配 |
|
pvFindPara的数据类型：未使用。
查找具有跨证书分发点扩展或属性的证书。 |
|
pvFindPara的数据类型：CRYPT_HASH_BLOB 结构。
查找与指定哈希匹配的 MD5 哈希公钥的证书。 |
[in] pvFindPara
指向与 dwFindType一起使用的数据项或结构。
[in] pPrevCertContext
指向此函数返回的最后一个 CERT_CONTEXT 结构的指针。 此参数必须在函数的第一次调用时 NULL。 若要查找符合搜索条件的连续证书，请将 pPrevCertContext 设置为上一次调用函数返回的指针。 此函数释放参数的非NULL 值引用的 CERT_CONTEXT。
返回值
如果函数成功，该函数将返回指向只读 CERT_CONTEXT 结构的指针。
如果函数失败，并且找不到与搜索条件匹配的证书，则返回值 NULL。
CertFindCertificateInStore 返回的非NULLCERT_CONTEXT 必须由 CertFreeCertificateContext 释放，或在后续调用 CertFindCertificateInStore时作为 pPrevCertContext 参数传递。
有关扩展错误信息，请调用 GetLastError。 下面是一些可能的错误代码。
| 返回代码 | 描述 |
|---|---|
|
找不到与搜索条件匹配的证书。 如果商店为空或到达商店列表的末尾，则可能会发生这种情况。 |
|
hCertStore 参数中的句柄与 pPrevCertContext 参数所指向的证书 上下文 中的句柄不同，或者 dwFindType 参数中指定的值无效。 |
言论
dwFindFlags 参数用于修改某些搜索类型的条件。
CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags 值仅用于 dwFindType的CERT_FIND_SUBJECT_ATTR和CERT_FIND_ISSUER_ATTR值。 如果使用 Unicode 字符串初始化 pvFindPara 所指向的 CERT_RDN_ATTR 结构，则必须设置CERT_UNICODE_IS_RDN_ATTRS_FLAG。 在进行任何比较之前，将使用X509_UNICODE_NAME来转换要匹配的字符串，以提供 Unicode 比较。
以下 dwFindFlags 值仅用于 dwFindType的CERT_FIND_ENKEY_USAGE值：
可以调用 CertDuplicateCertificateContext 来复制返回的上下文。 通过使用 CertAddCertificateContextToStore，可以将返回的上下文添加到其他 证书存储，也可以使用 CertAddCertificateLinkToStore将该证书上下文的链接添加到不是集合存储的存储中。
在后续调用函数时，返回的指针作为 pPrevCertContext 参数传递时释放。 否则，必须通过调用 CertFreeCertificateContext显式释放指针。 CertFindCertificateInStore 调用 CertFreeCertificateContext（即使函数中有错误）始终释放 NULL 的 pPrevCertContext。
例子
以下示例演示如何在满足搜索条件的证书存储中查找证书上下文。 有关包含此示例上下文的完整示例，请参阅 示例 C 程序：证书存储操作。
有关使用此函数的另一个示例，请参阅 示例 C 程序：集合和同级证书存储操作。
#include <windows.h>
#include <stdio.h>
#include <Wincrypt.h>
#pragma comment(lib, "crypt32.lib")
#define MY_ENCODING_TYPE (PKCS_7_ASN_ENCODING | X509_ASN_ENCODING)
void main()
{
//-------------------------------------------------------------------
// Declare and initialize variables.
HCERTSTORE hSystemStore; // The system store handle.
PCCERT_CONTEXT pDesiredCert = NULL; // Set to NULL for the first
// call to
// CertFindCertificateInStore.
LPCSTR lpszCertSubject = (LPCSTR) "Cert_subject_1";
//-------------------------------------------------------------------
// Open the certificate store to be searched.
if(hSystemStore = CertOpenStore(
CERT_STORE_PROV_SYSTEM,
0, // Encoding type not needed
// with this PROV.
NULL, // Accept the default HCRYPTPROV.
CERT_SYSTEM_STORE_CURRENT_USER,
// Set the system store location in
// the registry.
L"MY")) // Could have used other predefined
// system stores
// including Trust, CA, or Root.
{
printf("Opened the MY system store. \n");
}
else
{
printf( "Could not open the MY system store.\n");
exit(1);
}
//-------------------------------------------------------------------
// Get a certificate that has lpszCertSubject as its
// subject.
if(pDesiredCert=CertFindCertificateInStore(
hSystemStore,
MY_ENCODING_TYPE, // Use X509_ASN_ENCODING.
0, // No dwFlags needed.
CERT_FIND_SUBJECT_STR, // Find a certificate with a
// subject that matches the string
// in the next parameter.
lpszCertSubject , // The Unicode string to be found
// in a certificate's subject.
NULL)) // NULL for the first call to the
// function. In all subsequent
// calls, it is the last pointer
// returned by the function.
{
printf("The desired certificate was found. \n");
}
else
{
printf("Could not find the desired certificate.\n");
}
//-------------------------------------------------------------------
// Clean up.
if(pDesiredCert)
CertFreeCertificateContext(pDesiredCert);
if(hSystemStore)
CertCloseStore(
hSystemStore,
CERT_CLOSE_STORE_CHECK_FLAG);
要求
| 要求 | 价值 |
|---|---|
| 最低支持的客户端 | Windows XP [桌面应用 |UWP 应用] |
| 支持的最低服务器 | Windows Server 2003 [桌面应用 |UWP 应用] |
| 目标平台 | 窗户 |
| 标头 | wincrypt.h |
| 库 | Crypt32.lib |
| DLL | Crypt32.dll |
另请参阅
CertAddCertificateContextToStore