Fonction CertFindChainInStore (wincrypt.h)

Article
08/27/2023

La fonction CertFindChainInStore recherche le premier certificat 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ètres dwFindFlags, dwFindType et 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 créer 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 un certificat sur lequel une chaîne est générée. Ce handle est passé en tant que magasin supplémentaire à la fonction CertGetCertificateChain lorsque la chaîne est générée.

[in] dwCertEncodingType

Type d’encodage de certificat utilisé pour encoder le magasin. L’identificateur de type d’encodage de message, contenu dans le mot é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 du 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 à la clé publique du fournisseur de services de chiffrement. Cette comparaison est la dernière case activée effectuée sur la chaîne lors de sa génération. Étant donné que le membre hCryptProv d’un émetteur contient une clé privée, il peut être nécessaire de le vérifier plusieurs fois au cours de ce processus ; pour faciliter cette vérification, le membre dwAcquirePrivateKeyFlags peut être défini dans la structure CERT_CHAIN_FIND_BY_ISSUER_PARA pour activer la mise en cache de ce 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 d’émetteur. Avec ce jeu d’indicateurs, 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’obligeant à rechercher uniquement les magasins système mis en cache (Racine, My, Ca, Approbation) pour rechercher les 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 fait l’objet d’une recherche. Internet ne fait pas l’objet d’une recherche.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Ouvre uniquement les magasins de certificats d’ordinateur local. Les magasins de certificats de l’utilisateur actuel ne sont pas ouverts.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Aucune case activée 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 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 créé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 d’émetteur qui correspond à l’un des noms d’émetteurs.

Cette fonction compare les objets blob de noms passés dans la structure pvFindPara à n’importe quelle autorité de certification de 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’a pas la valeur 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 qu’il existe deux autorités de certification émettrices correspondantes, dont l’une est révoquée, cette fonction peut retourner 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 CertVerifyRevocation et trouve que la chaîne ne convient pas, 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. Au lieu de cela, il retourne une chaîne complètement différente avec un autre certificat 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 vers laquelle pointe ce paramètre dépendent de la valeur du paramètre dwFindType .

[in] pPrevChainContext

Pointeur vers une structure CERT_CHAIN_CONTEXT retournée à partir d’un appel précédent à cette fonction. La recherche commence à partir de ce certificat. Pour le premier appel à cette fonction, ce paramètre doit avoir la valeur 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 retournée

Si le premier ou le prochain contexte de chaîne n’est pas généré, null est retourné. Sinon, un pointeur vers une structure 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 avoir la valeur NULL lors du 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.

Configuration requise


Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincrypt.h
Bibliothèque	Crypt32.lib
DLL	Crypt32.dll