Fonction CertFindCertificateInStore (wincrypt.h)
La fonction
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é. Le certificat et types d’encodage de message doivent être spécifiés en les combinant avec une opérationOU 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 des 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 être l’une des valeurs suivantes.
| Valeur | Signification |
|---|---|
|
Type de données de pvFindPara: NULL , non utilisé.
Aucun critère de recherche n’est utilisé. Retourne le certificat suivant dans le magasin.
Remarque L’ordre du contexte de certificat peut ne pas être conservé dans le magasin.
Pour accéder à un certificat spécifique, vous devez itérer sur les certificats du magasin.
|
|
Type de données de pvFindPara: structure CERT_ID.
Recherchez le certificat identifié par le CERT_IDspé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 une extension 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 de CERT_EXTENSION avec le membre pszObjId défini sur szOID_ENHANCED_KEY_USAGE. Un certificat a une propriété d’utilisation améliorée de la clé si son identificateur 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 d’utilisation de la clé ou la propriété sont également des correspondances. La définition de cet indicateur est prioritaire sur le passage NULL dans pvFindPara. Si CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG est définie, 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: structure CERT_CONTEXT.
Recherche un certificat correspondant 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 le disque. La clé peut être une clé CAPI (Cryptography API) héritée ou une clé CNG.
Remarque 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 aux attributs de 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. Compare les itérations par le biais 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 est NULL, l’identificateur d’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type valeur est ignoré. Si le pbData membre de CERT_RDN_VALUE_BLOB est NULL, toute valeur correspond. 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: structure CERT_NAME_BLOB.
Recherchez un certificat avec une correspondance exacte de l’intégralité du nom de l’émetteur avec le nom dans CERT_NAME_BLOB La recherche est limitée aux certificats qui correspondent au dwCertEncodingType. |
|
Type de données de pvFindPara: structure CERT_CONTEXT.
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 de l’é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 mis en forme comme 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 le sujet 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 |
|
Type de données de pvFindPara: structure CERT_PUBLIC_KEY_INFO.
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 SHA1 + SHA256 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 SHA256 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 aux attributs de la structure CERT_RDN. Si les 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. Compare les itérations par le biais des 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 est NULL, l’identificateur d’objet d’attribut est ignoré. Si le membre dwValueType de CERT_RDN_ATTR est CERT_RDN_ANY_TYPE, le type valeur est ignoré. Si le pbData membre de CERT_RDN_VALUE_BLOB est NULL, toute valeur correspond. 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: structure CERT_INFO.
Recherche un certificat avec 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 de l’intégralité du nom de l’objet 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 de l’objet du certificat est converti en chaîne de nom du type approprié à l’aide de la forme appropriée de CertNameToStr mis en forme comme 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. |
|
Type de données de pvFindPara: non utilisé.
Recherchez un certificat qui a une extension ou une propriété de point de distribution de certificat croisé. |
|
Type de données de pvFindPara: structure CRYPT_HASH_BLOB.
Recherchez un certificat dont la clé publique md5 hachée 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 être NULL lors du premier appel de la fonction. Pour rechercher des certificats successifs répondant aux critères de recherche, définissez pPrevCertContext au pointeur retourné par l’appel précédent à la fonction. Cette fonction libère les CERT_CONTEXT référencées par des valeurs null nonNULL de ce paramètre.
Valeur de retour
Si la fonction réussit, la fonction renvoie un pointeur vers une structure de CERT_CONTEXT en lecture seule.
Si la fonction échoue et qu’un certificat qui correspond aux critères de recherche est introuvable, la valeur de retour est NULL.
Une
Pour obtenir des informations d’erreur étendues, appelez GetLastError. Certains codes d’erreur possibles suivent.
| Retourner le code | Description |
|---|---|
|
Aucun certificat n’a été trouvé correspondant aux critères de recherche. Cela peut se produire si le magasin est vide ou si la fin de la liste du magasin est atteinte. |
|
Le handle du paramètre hCertStore |
Remarques
Le paramètre dwFindFlags est utilisé pour modifier les critères de certains types de recherche.
La valeur dwFindFlags CERT_UNICODE_IS_RDN_ATTRS_FLAG
Les valeurs de dwFindFlags suivantes sont utilisées uniquement avec la valeur de CERT_FIND_ENKEY_USAGE pour dwFindType:
CertDuplicateCertificateContext peut être appelé pour effectuer un doublon du contexte retourné. Le contexte retourné peut être ajouté à un autre magasin de certificats en utilisant 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 ultérieur à la fonction. Sinon, le pointeur doit être explicitement libéré en appelant CertFreeCertificateContext. Un pPrevCertContext qui n’est pas NULL est toujours libéré par CertFindCertificateInStore à l’aide d’un appel à CertFreeCertificateContext, même s’il existe une erreur dans la fonction.
Exemples
L’exemple suivant montre la recherche d’un contexte de certificat dans le magasin de certificats répondant à 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 obtenir un autre exemple qui utilise cette fonction, consultez Exemple de programme C : opérations de magasin de certificats frères et de collection.
#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);
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 |
Voir aussi
CertAddCertificateContextToStore