Fonction CertFindCTLInStore (wincrypt.h)

Article
07/16/2024

La fonction CertFindCTLInStore recherche la première ou la liste de confiance de certificat suivante (CTL) contexte qui correspond aux critères de recherche établis par le dwFindType et son pvFindParaassocié. Cette fonction peut être utilisée dans une boucle pour rechercher tous les contextes de durée de vie dans un magasin de certificats qui correspondent aux critères de recherche spécifiés.

Syntaxe

PCCTL_CONTEXT CertFindCTLInStore(
  [in] HCERTSTORE    hCertStore,
  [in] DWORD         dwMsgAndCertEncodingType,
  [in] DWORD         dwFindFlags,
  [in] DWORD         dwFindType,
  [in] const void    *pvFindPara,
  [in] PCCTL_CONTEXT pPrevCtlContext
);

Paramètres

[in] hCertStore

Handle du magasin de certificats à rechercher.

[in] dwMsgAndCertEncodingType

Spécifie le type d’encodage utilisé sur la durée de vie. Il est toujours acceptable de spécifier à la fois le certificat et types d’encodage de message en les combinant avec une opération deOU 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

Ce paramètre est utilisé uniquement lorsque le paramètre dwFindType est défini sur CTL_FIND_USAGE.

[in] dwFindFlags

Peut être défini lorsque dwFindType est défini sur CTL_FIND_USAGE. Pour plus d’informations, consultez les commentaires sous CTL_FIND_USAGE, ci-dessous.

[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
CTL_FIND_ANY	Type de données de pvFindPara: NULL . Toute durée de vie est une correspondance.
CTL_FIND_SHA1_HASH	Type de données de pvFindPara: CRYPT_HASH_BLOB. Une durée de vie CTL avec un hachage correspondant au hachage dans la structure CRYPT_HASH_BLOB est trouvée.
CTL_FIND_MD5_HASH	Type de données de pvFindPara: CRYPT_HASH_BLOB. Une durée de vie CTL avec un hachage correspondant au hachage dans la structure CRYPT_HASH_BLOB est trouvée.
CTL_FIND_USAGE	Type de données de pvFindPara: CTL_FIND_USAGE_PARA. Toute durée de vie est trouvée avec un identificateur d’utilisation, un identificateur de liste ou un signataire correspondant à l’identificateur d’utilisation, à l’identificateur de liste ou au signataire dans la structure CTL_FIND_USAGE_PARA. Si le membre cUsageIdentifier est de taille SubjectUsage, toute durée de vie CTL est une correspondance. Si le membre cbData de ListIdentifier membre est égal à zéro, tout identificateur de liste est une correspondance. Si le membre cbData de ListIdentifier est CTL_FIND_NO_LIST_ID_CBDATA, seule une durée de vie CTL sans identificateur de liste est une correspondance. Si le membre pSigner dans la structure CTL_FIND_USAGE_PARA est NULL, tout signataire de la durée de vie est une correspondance, et seuls les membres Issuer et SerialNumber dans la structure pSignerCERT_INFO sont utilisés. Si pSigner est CTL_FIND_NO_SIGNER_PTR, seule une durée de vie CTL sans signataire est une correspondance.
CTL_FIND_SAME_USAGE_FLAG	Type de données de pvFindPara: CTL_FIND_USAGE_PARA. Seules les listes CTL avec exactement les mêmes identificateurs d’utilisation sont mises en correspondance. Les listes CTL ayant des identificateurs d’utilisation supplémentaires ne sont pas mises en correspondance. Par exemple, si seul « 1.2.3 » est spécifié dans la structure CTL_FIND_USAGE_PARA, pour une correspondance, la durée de vie doit contenir uniquement « 1.2.3 » et aucun identificateur d’utilisation supplémentaire.
CTL_FIND_EXISTING	Type de données de pvFindPara: PCCTL_CONTEXT. Recherche la liste de révocation de certificats suivante qui correspond exactement à la CTL_CONTEXT.
CTL_FIND_SUBJECT	Type de données de pvFindPara: CTL_FIND_SUBJECT_PARA. Une durée de vie contenant l’objet spécifié est trouvée. CertFindSubjectInCTL pouvez être appelée pour obtenir un pointeur vers l’entrée de l’objet dans la durée de vie. Le membre pUsagePara dans CTL_FIND_SUBJECT_PARA peut éventuellement être défini pour activer la correspondance décrite ci-dessus sous CTL_FIND_USAGE.

[in] pvFindPara

Pointeur vers la valeur de recherche associée au paramètre dwFindType.

[in] pPrevCtlContext

Pointeur vers la dernière CTL_CONTEXT retournée par cette fonction. Il doit être null pour obtenir la première durée de vie CTL dans le magasin. Les listes CTL successives sont récupérées en définissant pPrevCtlContext vers le pointeur vers le CTL_CONTEXT retourné par un appel de fonction précédent. Tous les certificats qui ne répondent pas aux critères de recherche ou qui ont été précédemment supprimés par CertDeleteCTLFromStore sont ignorés. Cette fonction libère les CTL_CONTEXT référencées par des valeurs null nonNULL de ce paramètre.

Valeur de retour

Si la fonction réussit, la valeur de retour est un pointeur vers une CTL en lecture seule contexte.

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

Retourner le code	Description
CRYPT_E_NOT_FOUND	Aucun CTL n’a été trouvé dans le magasin, aucune durée de vie n’a été trouvée correspondant aux critères de recherche, ou la fonction a atteint la fin de la liste du magasin.
E_INVALIDARG	Le handle dans le paramètre hCertStore n’est pas le même que dans le contexte de durée de vie indiqué par le paramètre pPrevCtlContext , ou une valeur qui n’est pas valide a été spécifiée dans le paramètre dwFindType.

Remarques

Un pointeur retourné est libéré lorsqu’il est passé en tant que pPrevCtlContext lors d’un appel ultérieur à la fonction. Sinon, le pointeur doit être libéré en appelant CertFreeCTLContext. UnNULLpPrevCtlContext transmis à la fonction est toujours libéré avec un appel à CertFreeCTLContext, même si la fonction génère une erreur.

CertDuplicateCTLContext peut être appelé pour effectuer un doublon du contexte retourné. Le contexte de durée de vie CTL retourné peut être ajouté à un autre magasin de certificats à l’aide de CertAddCTLContextToStore, ou un lien vers ce contexte de durée de vie peut être ajouté à un magasin de non-regroupements à l’aide de CertAddCTLLinkToStore. Si une durée de vie correspondant aux critères de recherche est introuvable, NULL est retournée.

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