Fonction CertFindCTLInStore (wincrypt.h)

Article
03/03/2024

La fonction CertFindCTLInStore recherche le premier ou le prochain contexte de liste d’approbation de certificats (CTL) qui correspond aux critères de recherche établis par le dwFindType et son pvFindPara associé. Cette fonction peut être utilisée dans une boucle pour rechercher tous les contextes CTL 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 CTL. Il est toujours acceptable de spécifier les types d’encodage de certificat et de message en les combinant avec une opération OR 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 prendre les valeurs suivantes.

Valeur	Signification
CTL_FIND_ANY	Type de données de pvFindPara : NULL. Toute CTL est une correspondance.
CTL_FIND_SHA1_HASH	Type de données de pvFindPara : CRYPT_HASH_BLOB. Une 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 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 CTL est trouvée qui a 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 CTL est une correspondance. Si le membre cbData du membre ListIdentifier 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 CTL sans identificateur de liste correspond. Si le membre pSigner dans la structure CTL_FIND_USAGE_PARA a la valeur NULL, tout signataire CTL est une correspondance et seuls les membres Issuer et SerialNumber de la structure pSignerCERT_INFO sont utilisés. Si pSigner est CTL_FIND_NO_SIGNER_PTR, seule une CTL sans signataire est une correspondance.
CTL_FIND_SAME_USAGE_FLAG	Type de données de pvFindPara : CTL_FIND_USAGE_PARA. Seules les listes de licences cloud avec exactement les mêmes identificateurs d’utilisation sont mises en correspondance. Les listes de contrôle client 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 de CTL_FIND_USAGE_PARA , pour une correspondance, la CTL ne doit contenir que « 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 CTL ayant le sujet spécifié est trouvée. CertFindSubjectInCTL peut être appelé pour obtenir un pointeur vers l’entrée du sujet dans la CTL. Le membre pUsagePara dans CTL_FIND_SUBJECT_PARA peut éventuellement être défini pour activer la correspondance décrite précédemment sous CTL_FIND_USAGE.

[in] pvFindPara

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

[in] pPrevCtlContext

Pointeur vers le dernier CTL_CONTEXT retourné par cette fonction. Elle doit être NULL pour obtenir la première CTL dans le magasin. Les listes CTL successives sont récupérées en définissant pPrevCtlContext sur 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és par des valeurs non NULL de ce paramètre.

Valeur retournée

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

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

Code de retour	Description
CRYPT_E_NOT_FOUND	Soit aucune CTL n’a été trouvée dans le magasin, aucune CTL 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 CTL pointé 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 suivant à la fonction. Sinon, le pointeur doit être libéré en appelant CertFreeCTLContext. Un pPrevCtlContext non NULL passé à 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 créer un doublon du contexte retourné. Le contexte CTL retourné peut être ajouté à un autre magasin de certificats à l’aide de CertAddCTLContextToStore, ou un lien vers ce contexte CTL peut être ajouté à un magasin de non-collection à l’aide de CertAddCTLLinkToStore. Si une CTL correspondant aux critères de recherche est introuvable, null est retourné.

Configuration requise

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