[This is preliminary documentation and subject to change.]
The CertFindCertificateInStore function finds in a certificate store the first or next certificate context that matches a search criteria. The search criteria is established by the dwFindType and its associated pvFindPara.
#include <wincrypt.h>
PCCERT_CONTEXT WINAPI CertFindCertificateInStore(
HCERTSTORE hCertStore, // in
DWORD dwCertEncodingType, // in
DWORD dwFindFlags, // in
DWORD dwFindType, // in
const void *pvFindPara, // in
PCCERT_CONTEXT pPrevCertContext // in
);
Currently defined encoding types are shown in the following table.
| Encoding type | Value |
|---|---|
| X509_ASN_ENCODING | 0x00000001 |
| PKCS_7_ASN_ENCODING | 0x00010000 |
Both a certificate and message encoding type should be specified. This is done by combining them with a bitwise OR operation, as shown in the following example:
X509_ASN_ENCODING | PKCS_7_ASN_ENCODING
| dwFindType | pvFindPara |
|---|---|
| CERT_FIND_ANY | NULL. pvFindPara not used |
| CERT_FIND_HASH | CRYPT_HASH_BLOB |
| CERT_FIND_SHA1_HASH | CRYPT_HASH_BLOB |
| CERT_FIND_MD5_HASH | CRYPT_HASH_BLOB |
| CERT_FIND_SIGNATURE_HASH | CRYPT_HASH_BLOB |
| CERT_FIND_PROPERTY | DWORD for the PROP_ID |
| CERT_FIND_PUBLIC_KEY | CERT_PUBLIC_KEY_INFO |
| CERT_FIND_SUBJECT_NAME | CERT_NAME_BLOB |
| CERT_FIND_ISSUER_NAME | CERT_NAME_BLOB |
| CERT_FIND_SUBJECT_ATTR | CERT_RDN structure |
| CERT_FIND_ISSUER_ATTR | CERT_RDN structure |
| CERT_FIND_SUBJECT_STR | NULL terminated wide (unicode) string |
| CERT_FIND_ISSUER_STR | NULL terminated wide (unicode) string |
| CERT_FIND_KEY_SPEC | DWORD for dwKeySpec |
| CERT_FIND_ENHKEY_USAGE | CERT_ENHKEY_USAGE structure |
| CERT_FIND_SUBJECT_CERT | CERT_INFO structure |
| CERT_FIND_ISSUER_OF | CERT_CONTEXT structure |
| CERT_FIND_EXISTING | CERT_CONTEXT structure |
Note There are alternate forms of find types that pass a string in pvFindPara. One form uses a unicode string and the other an ASCII string. Find types that end in "_W" or that end without a suffix use unicode. Find types that end with "_A" use ASCII strings.
If CERT_RDN_ATTR.pszObjId is NULL, the attribute object identifier is ignored.
If CERT_RDN_ATTR.dwValueType is CERT_RDN_ANY_TYPE, the value type is ignored.
If CERT_RDN_VALUE_BLOB.pbData is NULL, any value is a match.
Currently only an exact, case sensitive, match is supported. See the Remarks section for details on unicode options. The search is restricted to certificates matching the dwCertEncodingType.
| 1. | either the enhanced key usage extension or the enhanced key usage property and |
| 2. | usage identifiers that match the pszUsageIdentifers in the CERT_ENHKEY_USAGE data structure passed as pvFindPara. |
A certificate has the enhanced key usage extension if it has a CERT_EXTENSION with pszObjId set to szOID_ENHANCED_KEY_USAGE. It has the enhanced key usage property if its CERT_ENHKEY_USAGE_PROP_ID is set.
The pvFindPara parameter points to a CERT_ENHKEY_USAGE data structure. If pvFindPara is NULL or CERT_ENHKEY_USAGE.cUsageIdentifier is 0, no pszUsageIdentifers need to be matched and any certificate that has either the enhanced key usage extension or the enhanced key usage property meets the selection criteria.
See the Remarks section for details on flag modifications to find criteria.
This find type searches for a certificate having the szOID_ENHANCED_KEY_USAGE extension or the CERT_ENHKEY_USAGE_PROP_ID that matches the pszUsageIdentifer in the CERT_ENHKEY_USAGE structure pointed to by pvFindPara.
If pvFindPara is NULL or the cUsageIdentifier in the CERT_ENHKEY_USAGE structure is 0, any certificate having enhanced key usage is a match.
If CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG is set in dwFindFlags, certificates without the key usage extension or property are also matches.
If CERT_FIND_NO_ENHKEY_USAGE_FLAG is set in dwFindFlags, certificates without the key usage extension or property are found. 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 extension.
If a certificate that matches the search criteria is not found, NULL is returned. Otherwise, a pointer to a read-only CERT_CONTEXT is returned. A non-NULL CERT_CONTEXT returned must be freed by CertFreeCertificateContext or by being passed as pPrevCertContext on a subsequent call to CertFindCertificateInStore.
CertDuplicateCertificateContext can be called to make a duplicate of the returned context. The returned context may be added to a different certificate store using CertAddCertificateContextToStore or a link to that certificate context can be added to a non-collection store using CertAddCertificateLinkToStore
GetLastError may be called to indicate the reason for any failure. This function uses the following error codes:
| Error code | Description |
|---|---|
| E_INVALIDARG | The hCertStore argument isn't the same as the hCertStore of the certificate context pointed to by the pPrevCertContext argument or an invalid find type specified by dwFindType argument. |
| CRYPT_E_NOT_FOUND | No certificate was found matching the find criteria. This can happen if the store is empty or the end of the store's list is reached. |
The dwFindFlags parameter is used to modify the criteria of some search types.
The following dwFindFlags are used only with CERT_FIND_ENKEY_USAGE:
//
// Find a certificate meeting a specific search critera
// using CertFindCertificateInStore.
// In this case, a search is made for a certificate that has
// has a CERT_HASH_PROP_ID attached.
//
// handle_error() is a function defined in a separate file.
//
HCERTSTORE hStoreHandle;
PCCERT_CONTEXT pCertContext = NULL;
DWORD PropId = CERT_HASH_PROP_ID;
int i = 0;
// Open a certificate store.
// For details, see CertOpenStore.
if(hStoreHandle = CertOpenStore(
CERT_STORE_PROV_SYSTEM,0,NULL,CERT_SYSTEM_STORE_CURRENT_USER,
L"MY"))
printf("The MY store is open. Continue.\n");
else
handle_error("The store did not open.");
//
// Find all of the certificates in the store meeting the search
// criteria. In this case, in a loop find all certificates
// that have the CERT_HASH_PROP_ID property.
while ((pCertContext= CertFindCertificateInStore(
hStoreHandle, // Handle of the store to be searched.
0, // Encoding type. Not used for this search.
0, // dwFindFlags. Special find criteria.
// Not used in this search.
CERT_FIND_PROPERTY, // Find type. Determines the kind of search
// to be done. In this case, search for
// certificates that have a specific
// extended property.
&PropId, // pvFindPara. Gives the specific
// value searched for, here, the id of an
// extented property.
pCertContext))) // pCertContext is NULL for the
// first call to the function.
// If the function were being called
// in a loop, after the first call,
// pCertContext would be the cert
// returned by the previous call.
printf("Certificate %d has been retrieved.\n",++i);
//
// After the while loop, print a completion message.
printf("The process ran to completion with no errors.\n");
Windows NT: Requires version 4.0 SP3 or later. Available also in IE 3.02 and later.
Windows: Requires Windows 95 OSR2 or later.
Windows CE: Unsupported.
Header: Declared in wincrypt.h.
Import Library: Use crypt32.lib.