Fonction CertFindChainInStore (wincrypt.h)

Article
07/16/2024

La fonction CertFindChainInStore recherche le premier ou le certificat suivant dans un magasin qui répond aux critères spécifiés. Il génère et vérifie ensuite un contexte de chaîne de certificats pour ce certificat. Le certificat trouvé et pour lequel la chaîne est générée est sélectionné en fonction des critères établis par les paramètresdwFindFlags , dwFindTypeet paramètres pvFindPara. Cette fonction peut être utilisée dans une boucle pour rechercher tous les certificats d’un magasin de certificats qui correspondent aux critères de recherche spécifiés et pour générer un contexte de chaîne de certificats pour chaque certificat trouvé.

Syntaxe

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Paramètres

[in] hCertStore

Handle du magasin à rechercher pour obtenir un certificat sur lequel une chaîne est créée. Ce handle est passé en tant que magasin supplémentaire à la fonction CertGetCertificateChain à mesure que la chaîne est générée.

[in] dwCertEncodingType

Le type d’encodage de certificat utilisé pour encoder le magasin. Le type d’encodage de message identificateur, contenu dans le WORD élevé de cette valeur, est ignoré par cette fonction.

Ce paramètre peut être le type d’encodage de certificat actuellement défini ci-dessous.

Valeur	Signification
X509_ASN_ENCODING 1 (0x1)	Spécifie l’encodage de certificat X.509.

[in] dwFindFlags

Contient des options supplémentaires pour la recherche. Les valeurs possibles pour ce paramètre dépendent de la valeur du paramètre dwFindType.

Ce paramètre peut contenir zéro ou une combinaison d’une ou plusieurs des valeurs suivantes lorsque dwFindType contient CERT_CHAIN_FIND_BY_ISSUER.

Valeur	Signification
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Compare la clé publique dans le certificat avec le fournisseur de services de chiffrement clé publique. Cette comparaison est la dernière vérification effectuée sur la chaîne lorsqu’elle est générée. Étant donné que le hCryptProv membre d’un émetteur contient une clé privée, il peut être nécessaire de vérifier plusieurs fois pendant ce processus ; pour faciliter cette vérification, la dwAcquirePrivateKeyFlags membre peut être définie dans la structure CERT_CHAIN_FIND_BY_ISSUER_PARA pour activer la mise en cache de cette hCryptProv.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Par défaut, seule la première chaîne simple est vérifiée pour les correspondances de nom de l’émetteur. Avec cet indicateur défini, la valeur par défaut est remplacée et les chaînes simples suivantes sont également vérifiées pour les correspondances de nom de l’émetteur.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Améliore les performances de cette fonction en l’empêchant de rechercher uniquement les magasins système mis en cache (Racine, My, Ca, Approbation) pour rechercher des certificats d’émetteur. Si cet indicateur n’est pas défini, la fonction recherche les magasins système mis en cache et le magasin représenté par le paramètre hCertStore.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Seul le cache d’URL est recherché. Internet n’est pas recherché.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Ouvre uniquement les magasins de certificats ordinateur local. Les magasins de certificats de l’utilisateur actuel ne sont pas ouverts.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Aucune vérification n’est effectuée pour déterminer si le certificat a une clé privée associée.

[in] dwFindType

Détermine les critères à utiliser pour rechercher un certificat dans le magasin.

Ce paramètre peut être la valeur actuellement définie ci-dessous.

CERT_CHAIN_FIND_BY_ISSUER

Recherche le certificat en fonction du nom de l’émetteur. Le paramètre pvFindPara est un pointeur vers une structure CERT_CHAIN_FIND_BY_ISSUER_PARA qui contient des membres qui modifient la recherche.

La chaîne de certificats est générée pour un certificat avec une clé privée disponible. Par défaut, seuls les émetteurs de la première chaîne simple sont comparés dans une correspondance de nom d’émetteur. Si cet indicateur est défini, toutes les chaînes sont vérifiées pour un certificat émetteur qui correspond à l’un d’un ensemble de noms d’émetteurs.

Cette fonction compare le nom objets blob transmis dans la structure pvFindPara à n’importe quelle autorité de certification (CA) dans la chaîne, pas seulement l’autorité de certification dans le certificat racine.

Cette fonction n’effectue aucune vérification de révocation.

Si pPrevChainContext n’est pas NULL, cette fonction retourne une chaîne pour un certificat différent chaque fois que la fonction est appelée. S’il n’existe qu’un seul certificat approprié, mais il existe deux autorités de certification émettrices correspondantes, dont l’une est révoquée, il est possible que cette fonction retourne la chaîne révoquée. Si l’application vérifie ensuite la révocation elle-même par le biais d’appels à la fonction CertVerifyRevoc ation et recherche la chaîne inadaptée, un appel supplémentaire à la fonction CertFindChainInStore ne retourne pas une chaîne qui inclut le même certificat de l’autorité de certification valide. Elle retourne plutôt une chaîne complètement différente avec un certificat différent ou NULL, si aucune chaîne de ce type n’est trouvée.

[in] pvFindPara

Pointeur qui contient des critères de recherche supplémentaires. Le type et le format des données que ce paramètre pointe dépend de la valeur du paramètre dwFindType.

[in] pPrevChainContext

Pointeur vers une structure CERT_CHAIN_CONTEXT retournée par un appel précédent à cette fonction. La recherche est commencée à partir de ce certificat. Pour le premier appel à cette fonction, ce paramètre doit être NULL. Dans les appels suivants, il s’agit du pointeur retourné par l’appel précédent à la fonction. Si ce paramètre n’est pas NULL, cette fonction libère cette structure.

Valeur de retour

Si le premier ou le contexte de chaîne suivant n’est pas généré, NULL est retourné. Sinon, un pointeur vers une structure de CERT_CHAIN_CONTEXT en lecture seule est retourné. La structure CERT_CHAIN_CONTEXT est libérée lorsqu’elle est passée en tant que paramètre pPrevChainContext lors d’un appel ultérieur à cette fonction. Sinon, la structure CERT_CHAIN_CONTEXT doit être libérée explicitement en appelant la fonction CertFreeCertificateChain.

Remarques

Le paramètre pPrevChainContext doit être NULL sur le premier appel pour générer le contexte de chaîne. Pour générer le contexte de chaîne suivant, le pPrevChainContext est défini sur la structure CERT_CHAIN_CONTEXT retournée par un appel précédent. Si pPrevChainContext n’est pas NULL, la structure est toujours libérée par cette fonction à l’aide de la fonction CertFreeCertificateChain, même si une erreur se produit.

Exigences

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