Fonction CertFindCertificateInStore (wincrypt.h)
La fonction CertFindCertificateInStore recherche le premier ou le prochain contexte de certificats dans un magasin de certificats qui correspond à un critère de recherche établi par dwFindType et son pvFindPara associé. 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.
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é. Les types d’encodage de certificat et de message doivent être spécifiés 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
[in] dwFindFlags
Utilisé avec certaines 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 prendre les valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Type de données de pvFindPara : NULL, non utilisé.
Aucun critère de recherche utilisé. Retourne le certificat suivant dans le magasin. Note L’ordre du contexte de certificat peut ne pas être conservé dans le magasin.
Pour accéder à un certificat spécifique, vous devez effectuer une itération entre les certificats dans le magasin.
|
|
Type de données de pvFindPara : CERT_ID structure.
Recherchez le certificat identifié par le CERT_ID spécifié. |
|
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 . |
|
Type de données de pvFindPara : structure CERT_ENHKEY_USAGE .
Recherche un certificat dans le magasin qui a une extension d’utilisation 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 CERT_EXTENSION avec le membre pszObjId défini sur szOID_ENHANCED_KEY_USAGE. Un certificat a une propriété d’utilisation de clé améliorée si son identificateur de 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 ou la propriété d’utilisation de la clé sont également des correspondances. La définition de cet indicateur est prioritaire sur le passage de NULL dans pvFindPara. Si CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG est défini, 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. |
|
Type de données de pvFindPara : CERT_CONTEXT structure.
Recherche un certificat qui correspond exactement au contexte de certificat spécifié. |
|
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 . |
|
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 disque. La clé peut être une clé CAPI (Cryptography API) héritée ou une clé CNG. Note 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.
|
|
Type de données de pvFindPara : structure CERT_RDN .
Recherche un certificat avec des attributs d’émetteur spécifiés qui correspondent à des attributs dans 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 . Les comparaisons itèrent au sein 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 a la valeur NULL, l’identificateur de l’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type de valeur est ignoré. Si le membre pbData de CERT_RDN_VALUE_BLOB a la valeur NULL, toute valeur est une correspondance. 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. |
|
Type de données de pvFindPara : CERT_NAME_BLOB structure.
Recherchez un certificat avec une correspondance exacte du nom de l’émetteur entier avec le nom dans CERT_NAME_BLOB La recherche est limitée aux certificats qui correspondent à dwCertEncodingType. |
|
Type de données de pvFindPara : CERT_CONTEXT structure.
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 . |
|
Type de données de pvFindPara : chaîne Unicode terminée par null.
Recherche un certificat qui contient la chaîne de nom d’é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 au format 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 l’objet en chaîne Unicode et la correspondance de sous-chaîne est à nouveau effectuée. |
|
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. |
|
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. |
|
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. |
|
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. |
|
Type de données de pvFindPara : CERT_PUBLIC_KEY_INFO structure.
Recherche un certificat avec une clé publique qui correspond à la clé publique dans la structure CERT_PUBLIC_KEY_INFO . |
|
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 . |
|
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 . |
|
Type de données de pvFindPara : structure CERT_RDN .
Recherche un certificat avec des attributs d’objet spécifiés qui correspondent à des attributs dans la structure CERT_RDN . Si des 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 . Les comparaisons itèrent à travers les 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 a la valeur NULL, l’identificateur de l’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type de valeur est ignoré. Si le membre pbData de CERT_RDN_VALUE_BLOB a la valeur NULL, toute valeur est une correspondance. Actuellement, seule une correspondance exacte et respectant 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. |
|
Type de données de pvFindPara : structure CERT_INFO .
Recherche un certificat avec à la fois 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 . |
|
Type de données de pvFindPara : structure CERT_NAME_BLOB .
Recherche un certificat avec une correspondance exacte du nom de l’objet entier avec le nom dans la structure CERT_NAME_BLOB . La recherche est limitée aux certificats qui correspondent à la valeur de dwCertEncodingType. |
|
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 objet du certificat est converti en chaîne de nom du type approprié à l’aide de la forme appropriée de CertNameToStr mise en forme comme CERT_SIMPLE_NAME_STR. Ensuite, une correspondance de sous-chaîne insensible à 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. |
|
Type de données de pvFindPara : non utilisé.
Recherchez un certificat qui a une extension ou une propriété de point de distribution de certificats croisés. |
|
Type de données de pvFindPara : structure CRYPT_HASH_BLOB .
Recherchez un certificat dont la clé publique de hachage MD5 correspond au hachage spécifié. |
[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 avoir la valeur NULL lors du premier appel de la fonction. Pour rechercher les certificats successifs qui répondent aux critères de recherche, définissez pPrevCertContext sur le pointeur retourné par l’appel précédent à la fonction. Cette fonction libère les CERT_CONTEXT référencés par des valeurs non NULL de ce paramètre.
Valeur retournée
Si la fonction réussit, la fonction retourne un pointeur vers une structure de CERT_CONTEXT en lecture seule.
Si la fonction échoue et qu’un certificat correspondant aux critères de recherche est introuvable, la valeur de retour est NULL.
Un CERT_CONTEXT non NULL retourné par CertFindCertificateInStore doit être libéré par CertFreeCertificateContext ou passé 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.
| Code de retour | Description |
|---|---|
|
Aucun certificat correspondant aux critères de recherche n’a été trouvé. Cela peut se produire si le magasin est vide ou si la fin de la liste du magasin est atteinte. |
|
Le handle dans le 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 CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags est utilisée uniquement avec les valeurs CERT_FIND_SUBJECT_ATTR et CERT_FIND_ISSUER_ATTR pour dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG doit être défini si la structure CERT_RDN_ATTR pointée par pvFindPara a été initialisée avec des chaînes Unicode. Avant toute comparaison, la chaîne à mettre en correspondance est convertie à l’aide de X509_UNICODE_NAME pour fournir des comparaisons Unicode.
Les valeurs dwFindFlags suivantes sont utilisées uniquement avec la valeur CERT_FIND_ENKEY_USAGE pour dwFindType :
CertDuplicateCertificateContext peut être appelé pour créer un doublon du contexte retourné. Le contexte retourné peut être ajouté à un autre magasin de certificats à l’aide de 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 suivant à la fonction. Sinon, le pointeur doit être libéré explicitement en appelant CertFreeCertificateContext. Un pPrevCertContext qui n’est pas NULL est toujours libéré par CertFindCertificateInStore à l’aide d’un appel à CertFreeCertificateContext, même en cas d’erreur dans la fonction.
Exemples
L’exemple suivant montre comment trouver un contexte de certificat dans le magasin de certificats qui répond à 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 un autre exemple qui utilise cette fonction, consultez Exemple de programme C : Opérations de magasin de certificats de collection et frères.
#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);
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 |
Voir aussi
CertAddCertificateContextToStore
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour