CertFindCertificateInStore function (wincrypt.h)
The CertFindCertificateInStore function finds the first or next certificate context in a certificate store that matches a search criteria established by the dwFindType and its associated pvFindPara. This function can be used in a loop to find all of the certificates in a certificate store that match the specified find criteria.
Syntax
PCCERT_CONTEXT CertFindCertificateInStore(
[in] HCERTSTORE hCertStore,
[in] DWORD dwCertEncodingType,
[in] DWORD dwFindFlags,
[in] DWORD dwFindType,
[in] const void *pvFindPara,
[in] PCCERT_CONTEXT pPrevCertContext
);
Parameters
[in] hCertStore
A handle of the certificate store to be searched.
[in] dwCertEncodingType
Specifies the type of encoding used. Both the certificate and message encoding types must be specified by combining them with a bitwise-OR operation as shown in the following example:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING Currently defined encoding types are:
- X509_ASN_ENCODING
- PKCS_7_ASN_ENCODING
[in] dwFindFlags
Used with some dwFindType values to modify the search criteria. For most dwFindType values, dwFindFlags is not used and should be set to zero. For detailed information, see Remarks.
[in] dwFindType
Specifies the type of search being made. The search type determines the data type, contents, and the use of pvFindPara. This parameter can be one of the following values.
| Value | Meaning |
|---|---|
|
Data type of pvFindPara: NULL, not used.
No search criteria used. Returns the next certificate in the store. Note The order of the certificate context may not be preserved within the store.
To access a specific certificate you must iterate across the certificates in the store.
|
|
Data type of pvFindPara: CERT_ID structure.
Find the certificate identified by the specified CERT_ID. |
|
Data type of pvFindPara: CTL_USAGE structure.
Searches for a certificate that has a szOID_ENHANCED_KEY_USAGE extension or a CERT_CTL_PROP_ID that matches the pszUsageIdentifier member of the CTL_USAGE structure. |
|
Data type of pvFindPara: CERT_ENHKEY_USAGE structure.
Searches for a certificate in the store that has either an enhanced key usage extension or an enhanced key usage property and a usage identifier that matches the cUsageIdentifier member in the CERT_ENHKEY_USAGE structure. A certificate has an enhanced key usage extension if it has a CERT_EXTENSION structure with the pszObjId member set to szOID_ENHANCED_KEY_USAGE. A certificate has an enhanced key usage property if its CERT_ENHKEY_USAGE_PROP_ID identifier is set. If CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG is set in dwFindFlags, certificates without the key usage extension or property are also matches. Setting this flag takes precedence over passing NULL in pvFindPara. If CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG is set, a match is done only on the key usage extension. For information about flag modifications to search criteria, see Remarks. |
|
Data type of pvFindPara: CERT_CONTEXT structure.
Searches for a certificate that is an exact match of the specified certificate context. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a SHA1 hash that matches the hash in the CRYPT_HASH_BLOB structure. |
|
Data type of pvFindPara: NULL, not used.
Searches for a certificate that has a private key. The key can be ephemeral or saved on disk. The key can be a legacy Cryptography API (CAPI) key or a CNG key. Note The order of the certificate context may not be preserved within the store. Therefore, to access a specific certificate, you must iterate across all certificates.
|
|
Data type of pvFindPara: CERT_RDN structure.
Searches for a certificate with specified issuer attributes that match attributes in the CERT_RDN structure. If these values are set, the function compares attributes of the issuer in a certificate with elements of the CERT_RDN_ATTR array in this CERT_RDN structure. Comparisons iterate through the CERT_RDN_ATTR attributes looking for a match with the certificate's issuer attributes. If the pszObjId member of CERT_RDN_ATTR is NULL, the attribute object identifier is ignored. If the dwValueType member of CERT_RDN_ATTR is CERT_RDN_ANY_TYPE, the value type is ignored. If the pbData member of CERT_RDN_VALUE_BLOB is NULL, any value is a match. Currently only an exact, case-sensitive match is supported. For information about Unicode options, see Remarks. When these values are set, the search is restricted to certificates whose encoding type matches dwCertEncodingType. |
|
Data type of pvFindPara: CERT_NAME_BLOB structure.
Search for a certificate with an exact match of the entire issuer name with the name in CERT_NAME_BLOB The search is restricted to certificates that match the dwCertEncodingType. |
|
Data type of pvFindPara: CERT_CONTEXT structure.
Searches for a certificate with a subject that matches the issuer in CERT_CONTEXT. Instead of using CertFindCertificateInStore with this value, use the CertGetCertificateChain function. |
|
Data type of pvFindPara: Null-terminated Unicode string.
Searches for a certificate that contains the specified issuer name string. The certificate's issuer member is converted to a name string of the appropriate type using the appropriate form of CertNameToStr formatted as CERT_SIMPLE_NAME_STR. Then a case-insensitive substring-within-a-string match is performed. When this value is set, the search is restricted to certificates whose encoding type matches dwCertEncodingType. If the substring match fails and the subject contains an email RDN with Punycode encoded string, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG is used to convert the subject to a Unicode string and the substring match is performed again. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a CERT_KEY_IDENTIFIER_PROP_ID property that matches the key identifier in CRYPT_HASH_BLOB. |
|
Data type of pvFindPara: DWORD variable that contains a key specification.
Searches for a certificate that has a CERT_KEY_SPEC_PROP_ID property that matches the key specification in pvFindPara. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with an MD5 hash that matches the hash in CRYPT_HASH_BLOB. |
|
Data type of pvFindPara: DWORD variable that contains a property identifier.
Searches for a certificate with a property that matches the property identifier specified by the DWORD value in pvFindPara. |
|
Data type of pvFindPara: CERT_PUBLIC_KEY_INFO structure.
Searches for a certificate with a public key that matches the public key in the CERT_PUBLIC_KEY_INFO structure. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a SHA1 hash that matches the hash in the CRYPT_HASH_BLOB structure. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a SHA1 + SHA256 hash that matches the hash in the CRYPT_HASH_BLOB structure. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a SHA256 hash that matches the hash in the CRYPT_HASH_BLOB structure. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Searches for a certificate with a signature hash that matches the signature hash in the CRYPT_HASH_BLOB structure. |
|
Data type of pvFindPara: CERT_RDN structure.
Searches for a certificate with specified subject attributes that match attributes in the CERT_RDN structure. If RDN values are set, the function compares attributes of the subject in a certificate with elements of the CERT_RDN_ATTR array in this CERT_RDN structure. Comparisons iterate through the CERT_RDN_ATTR attributes looking for a match with the certificate's subject's attributes. If the pszObjId member of CERT_RDN_ATTR is NULL, the attribute object identifier is ignored. If the dwValueType member of CERT_RDN_ATTR is CERT_RDN_ANY_TYPE, the value type is ignored. If the pbData member of CERT_RDN_VALUE_BLOB is NULL, any value is a match. Currently only an exact, case-sensitive match is supported. For information about Unicode options, see Remarks. When these values are set, the search is restricted to certificates whose encoding type matches dwCertEncodingType. |
|
Data type of pvFindPara: CERT_INFO structure.
Searches for a certificate with both an issuer and a serial number that match the issuer and serial number in the CERT_INFO structure. |
|
Data type of pvFindPara: CERT_NAME_BLOB structure.
Searches for a certificate with an exact match of the entire subject name with the name in the CERT_NAME_BLOB structure. The search is restricted to certificates that match the value of dwCertEncodingType. |
|
Data type of pvFindPara: Null-terminated Unicode string.
Searches for a certificate that contains the specified subject name string. The certificate's subject member is converted to a name string of the appropriate type using the appropriate form of CertNameToStr formatted as CERT_SIMPLE_NAME_STR. Then a case-insensitive substring-within-a-string match is performed. When this value is set, the search is restricted to certificates whose encoding type matches dwCertEncodingType. |
|
Data type of pvFindPara: Not used.
Find a certificate that has either a cross certificate distribution point extension or property. |
|
Data type of pvFindPara: CRYPT_HASH_BLOB structure.
Find a certificate whose MD5-hashed public key matches the specified hash. |
[in] pvFindPara
Points to a data item or structure used with dwFindType.
[in] pPrevCertContext
A pointer to the last CERT_CONTEXT structure returned by this function. This parameter must be NULL on the first call of the function. To find successive certificates meeting the search criteria, set pPrevCertContext to the pointer returned by the previous call to the function. This function frees the CERT_CONTEXT referenced by non-NULL values of this parameter.
Return value
If the function succeeds, the function returns a pointer to a read-only CERT_CONTEXT structure.
If the function fails and a certificate that matches the search criteria is not found, the return value is NULL.
A non-NULL CERT_CONTEXT that CertFindCertificateInStore returns must be freed by CertFreeCertificateContext or by being passed as the pPrevCertContext parameter on a subsequent call to CertFindCertificateInStore.
For extended error information, call GetLastError. Some possible error codes follow.
| Return code | Description |
|---|---|
|
No certificate was found matching the search criteria. This can happen if the store is empty or the end of the store's list is reached. |
|
The handle in the hCertStore parameter is not the same as that in the certificate context pointed to by the pPrevCertContext parameter, or a value that is not valid was specified in the dwFindType parameter. |
Remarks
The dwFindFlags parameter is used to modify the criteria of some search types.
The CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags value is used only with the CERT_FIND_SUBJECT_ATTR and CERT_FIND_ISSUER_ATTR values for dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG must be set if the CERT_RDN_ATTR structure pointed to by pvFindPara was initialized with Unicode strings. Before any comparison is made, the string to be matched is converted by using X509_UNICODE_NAME to provide for Unicode comparisons.
The following dwFindFlags values are used only with the CERT_FIND_ENKEY_USAGE value for dwFindType:
CertDuplicateCertificateContext can be called to make a duplicate of the returned context. The returned context can be added to a different certificate store by using CertAddCertificateContextToStore, or a link to that certificate context can be added to a store that is not a collection store by using CertAddCertificateLinkToStore.
The returned pointer is freed when passed as the pPrevCertContext parameter on a subsequent call to the function. Otherwise, the pointer must be explicitly freed by calling CertFreeCertificateContext. A pPrevCertContext that is not NULL is always freed by CertFindCertificateInStore using a call to CertFreeCertificateContext, even if there is an error in the function.
Examples
The following example shows finding a certificate context in the certificate store meeting a search criterion. For a complete example that includes the context for this example, see Example C Program: Certificate Store Operations.
For another example that uses this function, see Example C Program: Collection and Sibling Certificate Store Operations.
#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);
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP [desktop apps | UWP apps] |
| Minimum supported server | Windows Server 2003 [desktop apps | UWP apps] |
| Target Platform | Windows |
| Header | wincrypt.h |
| Library | Crypt32.lib |
| DLL | Crypt32.dll |
See also
CertAddCertificateContextToStore