Fonction CertFindCertificateInStore (wincrypt.h)

Article
07/11/2024

La fonction CertFindCertificateInStore recherche le premier ou le contexte de de contexte suivant dans un magasin de certificats qui correspond à un critère de recherche établi par le dwFindType et son pvFindParaassocié. Cette fonction peut être utilisée dans une boucle pour rechercher tous les certificats dans un magasin de certificats qui correspondent aux critères de recherche spécifiés.

Syntaxe

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Paramètres

[in] hCertStore

Handle du magasin de certificats à rechercher.

[in] dwCertEncodingType

Spécifie le type d’encodage utilisé. Le certificat et types d’encodage de message doivent être spécifiés en les combinant avec une opérationOU au niveau du bit, comme illustré dans l’exemple suivant :

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING types d’encodage actuellement définis sont les suivants :

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFindFlags

Utilisé avec des valeurs dwFindType pour modifier les critères de recherche. Pour la plupart des valeurs dwFindType, dwFindFlags n’est pas utilisé et doit être défini sur zéro. Pour plus d’informations, consultez Remarques.

[in] dwFindType

Spécifie le type de recherche effectué. Le type de recherche détermine le type de données, le contenu et l’utilisation de pvFindPara. Ce paramètre peut être l’une des valeurs suivantes.

Valeur	Signification
CERT_FIND_ANY	Type de données de pvFindPara: NULL , non utilisé. Aucun critère de recherche n’est utilisé. Retourne le certificat suivant dans le magasin. Remarque L’ordre du contexte de certificat peut ne pas être conservé dans le magasin. Pour accéder à un certificat spécifique, vous devez itérer sur les certificats du magasin.
CERT_FIND_CERT_ID	Type de données de pvFindPara: structure CERT_ID. Recherchez le certificat identifié par le CERT_IDspécifié.
CERT_FIND_CTL_USAGE	Type de données de pvFindPara: structure CTL_USAGE. Recherche un certificat qui a une extension szOID_ENHANCED_KEY_USAGE ou un CERT_CTL_PROP_ID qui correspond au membre pszUsageIdentifier de la structure CTL_USAGE.
CERT_FIND_ENHKEY_USAGE	Type de données de pvFindPara: structure CERT_ENHKEY_USAGE. Recherche un certificat dans le magasin qui a une une extension de clé améliorée ou une propriété d’utilisation de clé améliorée et un identificateur d’utilisation qui correspond au membre cUsageIdentifier dans la structure CERT_ENHKEY_USAGE. Un certificat a une extension d’utilisation de clé améliorée s’il a une structure de CERT_EXTENSION avec le membre pszObjId défini sur szOID_ENHANCED_KEY_USAGE. Un certificat a une propriété d’utilisation améliorée de la clé si son identificateur CERT_ENHKEY_USAGE_PROP_ID est défini. Si CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG est défini dans dwFindFlags, les certificats sans l’extension d’utilisation de la clé ou la propriété sont également des correspondances. La définition de cet indicateur est prioritaire sur le passage NULL dans pvFindPara. Si CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG est définie, une correspondance est effectuée uniquement sur l’extension d’utilisation de la clé. Pour plus d’informations sur les modifications d’indicateur apportées aux critères de recherche, consultez Remarques.
CERT_FIND_EXISTING	Type de données de pvFindPara: structure CERT_CONTEXT. Recherche un certificat correspondant exactement au contexte de certificat spécifié.
CERT_FIND_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage SHA1 qui correspond au hachage dans la structure CRYPT_HASH_BLOB.
CERT_FIND_HAS_PRIVATE_KEY	Type de données de pvFindPara: NULL , non utilisé. Recherche un certificat qui a une clé privée. La clé peut être éphémère ou enregistrée sur le disque. La clé peut être une clé CAPI (Cryptography API) héritée ou une clé CNG. Remarque L’ordre du contexte de certificat peut ne pas être conservé dans le magasin. Par conséquent, pour accéder à un certificat spécifique, vous devez itérer sur tous les certificats. Windows 8 et Windows Server 2012 : prise en charge de cet indicateur commence.
CERT_FIND_ISSUER_ATTR	Type de données de pvFindPara: structure CERT_RDN. Recherche un certificat avec des attributs d’émetteur spécifiés qui correspondent aux attributs de la structure CERT_RDN. Si ces valeurs sont définies, la fonction compare les attributs de l’émetteur dans un certificat avec des éléments du tableau CERT_RDN_ATTR dans cette structure CERT_RDN. Compare les itérations par le biais des attributs CERT_RDN_ATTR à la recherche d’une correspondance avec les attributs d’émetteur du certificat. Si le membre pszObjId de CERT_RDN_ATTR est NULL, l’identificateur d’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type valeur est ignoré. Si le pbData membre de CERT_RDN_VALUE_BLOB est NULL, toute valeur correspond. Actuellement, seule une correspondance exacte et sensible à la casse est prise en charge. Pour plus d’informations sur les options Unicode, consultez Remarques. Lorsque ces valeurs sont définies, la recherche est limitée aux certificats dont le type d’encodage correspond dwCertEncodingType.
CERT_FIND_ISSUER_NAME	Type de données de pvFindPara: structure CERT_NAME_BLOB. Recherchez un certificat avec une correspondance exacte de l’intégralité du nom de l’émetteur avec le nom dans CERT_NAME_BLOB La recherche est limitée aux certificats qui correspondent au dwCertEncodingType.
CERT_FIND_ISSUER_OF	Type de données de pvFindPara: structure CERT_CONTEXT. Recherche un certificat avec un objet qui correspond à l’émetteur dans CERT_CONTEXT. Au lieu d’utiliser CertFindCertificateInStore avec cette valeur, utilisez la fonction CertGetCertificateChain.
CERT_FIND_ISSUER_STR	Type de données de pvFindPara: chaîne Unicode terminée par null. Recherche un certificat qui contient la chaîne de nom de l’émetteur spécifiée. Le membre émetteur du certificat est converti en chaîne de nom du type approprié à l’aide de la forme appropriée de CertNameToStr mis en forme comme CERT_SIMPLE_NAME_STR. Ensuite, une correspondance de sous-chaîne ne respectant pas la casse est effectuée. Lorsque cette valeur est définie, la recherche est limitée aux certificats dont le type d’encodage correspond dwCertEncodingType. Si la correspondance de sous-chaîne échoue et que l’objet contient un RDN d’e-mail avec une chaîne encodée Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG est utilisé pour convertir le sujet en chaîne Unicode et la correspondance de sous-chaîne est à nouveau effectuée.
CERT_FIND_KEY_IDENTIFIER	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec une propriété CERT_KEY_IDENTIFIER_PROP_ID qui correspond à l’identificateur de clé dans CRYPT_HASH_BLOB.
CERT_FIND_KEY_SPEC	Type de données de pvFindPara: variable DWORD qui contient une spécification de clé. Recherche un certificat qui a une propriété CERT_KEY_SPEC_PROP_ID qui correspond à la spécification de clé dans pvFindPara.
CERT_FIND_MD5_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage MD5 qui correspond au hachage dans CRYPT_HASH_BLOB.
CERT_FIND_PROPERTY	Type de données de pvFindPara: variable DWORD qui contient un identificateur de propriété. Recherche un certificat avec une propriété qui correspond à l’identificateur de propriété spécifié par la valeur DWORD dans pvFindPara.
CERT_FIND_PUBLIC_KEY	Type de données de pvFindPara: structure CERT_PUBLIC_KEY_INFO. Recherche un certificat avec une clé publique qui correspond à la clé publique dans la structure CERT_PUBLIC_KEY_INFO.
CERT_FIND_SHA1_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage SHA1 qui correspond au hachage dans la structure CRYPT_HASH_BLOB.
CERT_FIND_SHA1_SHA256_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage SHA1 + SHA256 qui correspond au hachage dans la structure CRYPT_HASH_BLOB.
CERT_FIND_SHA256_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage SHA256 qui correspond au hachage dans la structure CRYPT_HASH_BLOB.
CERT_FIND_SIGNATURE_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherche un certificat avec un hachage de signature qui correspond au hachage de signature dans la structure CRYPT_HASH_BLOB.
CERT_FIND_SUBJECT_ATTR	Type de données de pvFindPara: structure CERT_RDN. Recherche un certificat avec des attributs d’objet spécifiés qui correspondent aux attributs de la structure CERT_RDN. Si les valeurs RDN sont définies, la fonction compare les attributs de l’objet dans un certificat avec les éléments du tableau CERT_RDN_ATTR dans cette structure CERT_RDN. Compare les itérations par le biais des attributs CERT_RDN_ATTR à la recherche d’une correspondance avec les attributs de l’objet du certificat. Si le membre pszObjId de CERT_RDN_ATTR est NULL, l’identificateur d’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type valeur est ignoré. Si le pbData membre de CERT_RDN_VALUE_BLOB est NULL, toute valeur correspond. Actuellement, seule une correspondance exacte et sensible à la casse est prise en charge. Pour plus d’informations sur les options Unicode, consultez Remarques. Lorsque ces valeurs sont définies, la recherche est limitée aux certificats dont le type d’encodage correspond dwCertEncodingType.
CERT_FIND_SUBJECT_CERT	Type de données de pvFindPara: structure CERT_INFO. Recherche un certificat avec un émetteur et un numéro de série qui correspondent à l’émetteur et au numéro de série dans la structure CERT_INFO.
CERT_FIND_SUBJECT_NAME	Type de données de pvFindPara: structure CERT_NAME_BLOB. Recherche un certificat avec une correspondance exacte de l’intégralité du nom de l’objet avec le nom dans la structure CERT_NAME_BLOB. La recherche est limitée aux certificats qui correspondent à la valeur de dwCertEncodingType.
CERT_FIND_SUBJECT_STR	Type de données de pvFindPara: chaîne Unicode terminée par null. Recherche un certificat qui contient la chaîne de nom d’objet spécifiée. Le membre de l’objet du certificat est converti en chaîne de nom du type approprié à l’aide de la forme appropriée de CertNameToStr mis en forme comme CERT_SIMPLE_NAME_STR. Ensuite, une correspondance de sous-chaîne ne respectant pas la casse est effectuée. Lorsque cette valeur est définie, la recherche est limitée aux certificats dont le type d’encodage correspond dwCertEncodingType.
CERT_FIND_CROSS_CERT_DIST_POINTS	Type de données de pvFindPara: non utilisé. Recherchez un certificat qui a une extension ou une propriété de point de distribution de certificat croisé.
CERT_FIND_PUBKEY_MD5_HASH	Type de données de pvFindPara: structure CRYPT_HASH_BLOB. Recherchez un certificat dont la clé publique md5 hachée correspond au hachage spécifié.

Remarque Il existe d’autres formes de la valeur de dwFindType qui passent une chaîne dans pvFindPara. Un formulaire utilise une chaîne Unicode et l’autre une chaîne ASCII. Les valeurs qui se terminent par « _W » ou sans suffixe utilisent Unicode. Les valeurs qui se terminent par « _A » utilisent des chaînes ASCII.

[in] pvFindPara

Pointe vers un élément de données ou une structure utilisé avec dwFindType.

[in] pPrevCertContext

Pointeur vers la dernière structure CERT_CONTEXT retournée par cette fonction. Ce paramètre doit être NULL lors du premier appel de la fonction. Pour rechercher des certificats successifs répondant aux critères de recherche, définissez pPrevCertContext au pointeur retourné par l’appel précédent à la fonction. Cette fonction libère les CERT_CONTEXT référencées par des valeurs null nonNULL de ce paramètre.

Valeur de retour

Si la fonction réussit, la fonction renvoie un pointeur vers une structure de CERT_CONTEXT en lecture seule.

Si la fonction échoue et qu’un certificat qui correspond aux critères de recherche est introuvable, la valeur de retour est NULL.

UneCERT_CONTEXT NULL nonretournée par CertFindCertificateInStore doit être libérée par CertFreeCertificateContext ou en étant passée en tant que paramètre pPrevCertContext lors d’un appel ultérieur à CertFindCertificateInStore.

Pour obtenir des informations d’erreur étendues, appelez GetLastError. Certains codes d’erreur possibles suivent.

Retourner le code	Description
CRYPT_E_NOT_FOUND	Aucun certificat n’a été trouvé correspondant aux critères de recherche. Cela peut se produire si le magasin est vide ou si la fin de la liste du magasin est atteinte.
E_INVALIDARG	Le handle du paramètre hCertStore n’est pas le même que dans le contexte de certificat pointé par le paramètre pPrevCertContext, ou une valeur qui n’est pas valide a été spécifiée dans le paramètre dwFindType.

Remarques

Le paramètre dwFindFlags est utilisé pour modifier les critères de certains types de recherche.

La valeur dwFindFlags CERT_UNICODE_IS_RDN_ATTRS_FLAG est utilisée uniquement avec les valeurs de CERT_FIND_SUBJECT_ATTR et de CERT_FIND_ISSUER_ATTR pour dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG doit être définie si la structure CERT_RDN_ATTR pointée par pvFindPara a été initialisée avec des chaînes Unicode. Avant d’effectuer une comparaison, la chaîne à mettre en correspondance est convertie à l’aide de X509_UNICODE_NAME pour fournir des comparaisons Unicode.

Les valeurs de dwFindFlags suivantes sont utilisées uniquement avec la valeur de CERT_FIND_ENKEY_USAGE pour dwFindType:

CertDuplicateCertificateContext peut être appelé pour effectuer un doublon du contexte retourné. Le contexte retourné peut être ajouté à un autre magasin de certificats en utilisant CertAddCertificateContextToStore, ou un lien vers ce contexte de certificat peut être ajouté à un magasin qui n’est pas un magasin de collections à l’aide de CertAddCertificateLinkToStore.

Le pointeur retourné est libéré lorsqu’il est passé en tant que paramètre pPrevCertContext lors d’un appel ultérieur à la fonction. Sinon, le pointeur doit être explicitement libéré en appelant CertFreeCertificateContext. Un pPrevCertContext qui n’est pas NULL est toujours libéré par CertFindCertificateInStore à l’aide d’un appel à CertFreeCertificateContext, même s’il existe une erreur dans la fonction.

Exemples

L’exemple suivant montre la recherche d’un contexte de certificat dans le magasin de certificats répondant à un critère de recherche. Pour obtenir un exemple complet qui inclut le contexte de cet exemple, consultez Exemple de programme C : Opérations du magasin de certificats.

Pour obtenir un autre exemple qui utilise cette fonction, consultez Exemple de programme C : opérations de magasin de certificats frères et de collection.

#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);

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau \| Applications UWP]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau \| Applications UWP]
plateforme cible	Windows
d’en-tête	wincrypt.h
bibliothèque	Crypt32.lib
DLL	Crypt32.dll