Partager via

CertFindCertificateInStore (Compact 2013)

  • Article

3/28/2014

This function finds the first or next certificate context in a certificate store that matches search criteria established by the dwFindType parameter and its associated pvFindPara parameter. 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 WINAPI CertFindCertificateInStore(
  HCERTSTORE hCertStore, 
  DWORD dwCertEncodingType, 
  DWORD dwFindFlags, 
  DWORD dwFindType, 
  const void* pvFindPara, 
  PCCERT_CONTEXT pPrevCertContext
);

Parameters

  • hCertStore
    [in] Handle to the certificate store to be searched.
  • dwCertEncodingType
    [in] Specifies the type of encoding used. Only X509_ASN_ENCODING is used.
  • dwFindFlags
    [in] Specifies the modifier of search criteria when used with certain dwFindType values. For most dwFindType values, this parameter is not used and should be set to zero. For detailed information, see the Remarks section.

  • dwFindType
    [in] Specifies the type of search being made. The search type determines the data type, contents, and the use of pvFindPara. The following table shows each dwFindType value that is currently defined and the corresponding data type for the pvFindPara parameter.

    Value of dwFindType

    Value of pvFindPara

    Search criteria

    CERT_FIND_ANY

    NULL; pvFindPara not used

    No search criteria used. Returns the next certificate in the store.

    CERT_FIND_CERT_ID

    CERT_ID structure

    Finds the certificate identified by the specified CERT_ID.

    CERT_FIND_ENHKEY_USAGE

    CERT_ENHKEY_USAGE structure

    Searches for a certificate in the store having either an enhanced key usage extension or an enhanced key usage property and a usage identifier that matches the pszUsageIdentifier member in the CERT_ENHKEY_USAGE structure.

    A certificate has an enhanced key usage extension if it has a CERT_EXTENSIONstructure 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 pvFindPara is NULL or the cUsageIdentifier member of CERT_ENHKEY_USAGE is zero, any certificate that has either the enhanced key usage extension or the enhanced key usage property meets the selection criteria.

    If pvFindPara is NULL or the cUsageIdentifier member of CERT_ENHKEY_USAGE is zero, 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. 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 details on flag modifications to search criteria, see the Remarks section.

    CERT_FIND_EXISTING

    CERT_CONTEXTstructure

    Searches for a certificate that is an exact match of the specified certificate context.

    CERT_FIND_HASH

    CRYPT_HASH_BLOB structure

    Searches for a certificate with a SHA1 hash that matches the hash in the CRYPT_HASH_BLOB structure.

    CERT_FIND_ISSUER_ATTR

    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_RDNstructure. 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 the BLOB structure is NULL, any value is a match.

    Currently only an exact, case-sensitive match is supported. For details on Unicode options, see the Remarks section. When these values are set, the search is restricted to certificates whose encoding type matches the dwCertEncodingType value.

    CERT_FIND_ISSUER_NAME

    CERT_NAME_BLOB structure

    Searches 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.

    CERT_FIND_ISSUER_OF

    CERT_CONTEXT structure

    Searches for a certificate with an issuer that matches the issuer in CERT_CONTEXT.

    Instead of using CertFindCertificateInStore with this value, use the CertGetCertificateChain function.

    CERT_FIND_ISSUER_STR

    Null-terminated wide (Unicode) string

    Searches for a certificate containing 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.

    CERT_FIND_KEY_IDENTIFIER

    CRYPT_HASH_BLOB structure

    Searches for a certificate with a CERT_KEY_IDENTIFIER_PROP_ID property matching the key identifier in CRYPT_HASH_BLOB.

    CERT_FIND_KEY_SPEC

    DWORD containing a key specification

    Searches for a certificate having a CERT_KEY_SPEC_PROP_ID property matching the key specification in pvFindPara.

    CERT_FIND_MD5_HASH

    CRYPT_HASH_BLOB structure

    Searches for a certificate with an MD5 hash that matches the hash in CRYPT_HASH_BLOB.

    CERT_FIND_PROPERTY

    DWORD containing a property identifier

    Searches for a certificate with a property that matches the property identifier specified by the DWORD in pvFindPara.

    CERT_FIND_PUBLIC_KEY

    CERT_PUBLIC_KEY_INFO structure

    Searches for a certificate with a public key that matches the public key in CERT_PUBLIC_KEY_INFO.

    CERT_FIND_SHA1_HASH

    CRYPT_HASH_BLOB structure

    Searches for a certificate with a SHA1 hash that matches the hash in CRYPT_HASH_BLOB.

    CERT_FIND_SIGNATURE_HASH

    CRYPT_HASH_BLOB structure

    Searches for a certificate with a signature hash that matches the signature hash in CRYPT_HASH_BLOB.

    CERT_FIND_SUBJECT_ATTR

    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_RDNstructure. Comparisons iterate through the CERT_RDN_ATTR attributes looking for a match with the certificate's subject 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 the CERT_RDN_VALUE_BLOB structure is NULL, any value is a match.

    Currently only an exact, case-sensitive match is supported.

    For details on Unicode options, see the Remarks section. When these values are set, the search is restricted to certificates whose encoding type matches dwCertEncodingType.

    CERT_FIND_SUBJECT_CERT

    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.

    CERT_FIND_SUBJECT_NAME

    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.

    CERT_FIND_SUBJECT_STR

    NULL-terminated wide (Unicode) string

    Searches for a certificate containing 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.

    There are alternate forms of the dwFindType value that pass a string in pvFindPara. One form uses a Unicode string, and the other an ASCII string. Values that end in _W or without a suffix use Unicode. Values that end with _A use ASCII strings.

  • pvFindPara
    [in] Pointer to a data item or structure used with the dwFindType parameter.
  • pPrevCertContext
    [in] Pointer to the last CERT_CONTEXT structure returned by this function. This parameter must be NULL on the first call of the function. A pPrevCertContext parameter that is not NULLis always freed by this function, even if the function causes an error.

Return Value

If the function succeeds, the return value is 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 structure that the CertFindCertificateInStore function returns must be freed by the CertFreeCertificateContext function or by being passed as the pPrevCertContext parameter on a subsequent call to the CertFindCertificateInStore function.

For extended error information, call the GetLastError function. The following table shows some possible error codes.

Error value

Description

CRYPT_E_NOT_FOUND

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.

E_INVALIDARG

The handle in the hCertStore parameter is not the same as that in the certificate context pointed to by the pPrevCertContext parameter, or an invalid value 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 value for the dwFindFlags parameter 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:

  • CERT_FIND_OR_ENHKEY_USAGE_FLAG
    The search criteria can be altered by setting one or more flags. By default, if the pszUsageIdentifer member of the CERT_ENHKEY_USAGE structure pointed to by e pvFindPara is to be matched, each identifier must be matched to satisfy the search criteria. However, if CERT_FIND_OR_ENHKEY_USAGE_FLAG is set, a match can be made to all identifiers combined by using a bitwise OR operation; thus, matching any one of the identifiers is sufficient.
  • CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG
    When this flag is set, in addition to usual matches, any certificate that has neither the enhanced key usage extension nor the enhanced key usage property meets the search criteria.
  • CERT_FIND_NO_ENHKEY_USAGE_FLAG
    When this flag is set, only those certificates that have neither an enhanced key usage nor the enhanced key usage property are matches. This flag setting takes precedence over pvFindPara being NULL.
  • CERT_FIND_VALID_ENHKEY_USAGE_FLAG
    When this flag is set, the function only matches those certificates that are valid for the specified usage. By default, in order to match, a certificate must be valid for all usages.
    CERT_FIND_OR_ENHKEY_USAGE_FLAG can also be set if the certificate only needs to be valid for one of the specified usages. Note that the CertGetValidUsages function is called to get the certificate's list of valid usages. Only CERT_FIND_OR_ENHKEY_USAGE_FLAG can also apply when CERT_FIND_VALID_ENHKEY_USAGE_FLAG is set.
  • CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG
    When this flag is set, the matching process involves only the extension usage identifiers. If pvFindPara is NULL or the cUsageIdentifier member of the CERT_ENHKEY_USAGE structure pointed to by pvFindPara is zero, any certificate having an enhanced key usage extension is a match. If CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG is also set, any certificate without the enhanced key usage extension is also a match. If CERT_FIND_NO_ENHKEY_USAGE_FLAG is also set, only certificates without the enhanced key usage extension are matches.
  • CERT_FIND_EXT_PROP_ENHKEY_USAGE_FLAG
    When this flag is set, the matching process involves only usage identifiers that are properties. If pvFindPara is NULL or the cUsageIdentifier member is set to zero, any certificate having an enhanced key usage property is a match. If CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG is also set, any certificate without the enhanced key usage property is also a match. If CERT_FIND_NO_ENHKEY_USAGE_FLAG is set, only certificates without the enhanced key usage property are matches.
  • CERT_CASE_INSENSITIVE_IS_RDN_ATTRS_FLAG
    This flag is used only with CERT_FIND_SUBJECT_ATTR and CERT_FIND_ISSUER-ATTR values of the dwFindType parameter. By default, a case-sensitive, exact match is made. If this flag is set, the match is case-insensitive.

The CertDuplicateCertificateContext function can be called to make a duplicate of the returned context. The returned context can be added to a different certificate store using the CertAddCertificateContextToStore function,or a link to that certificate context can be added to a noncollection store using the CertAddCertificateLinkToStore function.

The desktop operating system supports the flag PKCS_7_ASN_ENCODING, but Windows Embedded Compact does not and ignores the flag when it is specified.

The desktop operating system supports the CERT_FIND_CTL_USAGE dwFindType flag; Windows Embedded Compact does not.

Requirements

Header

wincrypt.h

Library

crypt32.lib

See Also

Reference

Certificates Functions
CertAddCertificateContextToStore
CertAddCertificateLinkToStore
CertDuplicateCertificateContext
CertFreeCertificateContext
CertGetCertificateChain
CertNameToStr
CERT_CONTEXT
CTL_USAGE
CERT_EXTENSION
CERT_ID
CERT_INFO
BLOB (Cryptography)
CERT_PUBLIC_KEY_INFO
CERT_RDN
CERT_RDN_ATTR
BLOB (Cryptography)
BLOB (Cryptography)