Funzione CertFindCertificateInStore (wincrypt.h)

Articolo
07/11/2024

La funzione CertFindCertificateInStore trova il primo o il successivo contesto del certificato in un archivio certificati che corrisponde a un criterio di ricerca stabilito dal dwFindType e dal relativo pvFindParaassociato. Questa funzione può essere usata in un ciclo per trovare tutti i certificati in un archivio certificati che corrispondono ai criteri di ricerca specificati.

Sintassi

PCCERT_CONTEXT CertFindCertificateInStore(
  [in] HCERTSTORE     hCertStore,
  [in] DWORD          dwCertEncodingType,
  [in] DWORD          dwFindFlags,
  [in] DWORD          dwFindType,
  [in] const void     *pvFindPara,
  [in] PCCERT_CONTEXT pPrevCertContext
);

Parametri

[in] hCertStore

Handle dell'archivio certificati da cercare.

[in] dwCertEncodingType

Specifica il tipo di codifica utilizzata. Sia il certificato che i tipi di codifica dei messaggi devono essere specificati combinandoli con un'operazioneOR bit per bit, come illustrato nell'esempio seguente:

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING I tipi di codifica attualmente definiti sono:

X509_ASN_ENCODING
PKCS_7_ASN_ENCODING

[in] dwFindFlags

Usato con alcuni valori dwFindType per modificare i criteri di ricerca. Per la maggior parte dei valori dwFindType, dwFindFlags non viene usato e deve essere impostato su zero. Per informazioni dettagliate, vedere Osservazioni.

[in] dwFindType

Specifica il tipo di ricerca in corso. Il tipo di ricerca determina il tipo di dati, il contenuto e l'uso di pvFindPara. Questo parametro può essere uno dei valori seguenti.

Valore	Significato
CERT_FIND_ANY	Tipo di dati di pvFindPara: NULL, non usato. Nessun criterio di ricerca utilizzato. Restituisce il certificato successivo nell'archivio. Nota L'ordine del contesto del certificato potrebbe non essere mantenuto all'interno dell'archivio. Per accedere a un certificato specifico, è necessario scorrere i certificati nell'archivio.
CERT_FIND_CERT_ID	Tipo di dati di pvFindPara: struttura CERT_ID. Trovare il certificato identificato dal CERT_IDspecificato.
CERT_FIND_CTL_USAGE	Tipo di dati di pvFindPara: struttura CTL_USAGE. Cerca un certificato con estensione szOID_ENHANCED_KEY_USAGE o un CERT_CTL_PROP_ID corrispondente al membro pszUsageIdentifier membro della struttura CTL_USAGE.
CERT_FIND_ENHKEY_USAGE	Tipo di dati di pvFindPara: struttura CERT_ENHKEY_USAGE. Cerca un certificato nell'archivio con un'estensione utilizzo chiavi avanzato o una proprietà di utilizzo chiave avanzata e un identificatore di utilizzo corrispondente al membro cUsageIdentifier nella struttura di CERT_ENHKEY_USAGE. Un certificato ha un'estensione avanzata per l'utilizzo delle chiavi se ha una struttura di CERT_EXTENSION con il membro pszObjId impostato su szOID_ENHANCED_KEY_USAGE. Un certificato ha una proprietà di utilizzo chiavi avanzata se è impostato il relativo identificatore CERT_ENHKEY_USAGE_PROP_ID. Se CERT_FIND_OPTIONAL_ENHKEY_USAGE_FLAG è impostato in dwFindFlags, anche i certificati senza l'estensione o la proprietà di utilizzo della chiave corrispondono. L'impostazione di questo flag ha la precedenza sul passaggio di NULL in pvFindPara. Se CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG è impostato, viene eseguita una corrispondenza solo sull'estensione di utilizzo delle chiavi. Per informazioni sulle modifiche dei flag ai criteri di ricerca, vedere Osservazioni.
CERT_FIND_EXISTING	Tipo di dati di pvFindPara: struttura CERT_CONTEXT. Cerca un certificato che corrisponde esattamente al contesto del certificato specificato.
CERT_FIND_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash SHA1 che corrisponde all'hash nella struttura CRYPT_HASH_BLOB.
CERT_FIND_HAS_PRIVATE_KEY	Tipo di dati di pvFindPara: NULL, non usato. Cerca un certificato con una chiave privata. La chiave può essere temporanea o salvata su disco. La chiave può essere una chiave DELL'API di crittografia legacy (CAPI) o una chiave CNG. Nota L'ordine del contesto del certificato potrebbe non essere mantenuto all'interno dell'archivio. Pertanto, per accedere a un certificato specifico, è necessario scorrere tutti i certificati. Windows 8 e Windows Server 2012: viene avviato il supporto per questo flag.
CERT_FIND_ISSUER_ATTR	Tipo di dati di pvFindPara: struttura CERT_RDN. Cerca un certificato con attributi dell'autorità di certificazione specificati che corrispondono agli attributi nella struttura CERT_RDN. Se questi valori sono impostati, la funzione confronta gli attributi dell'autorità emittente in un certificato con gli elementi della matrice CERT_RDN_ATTR in questa struttura CERT_RDN. I confronti eseguano l'iterazione degli attributi CERT_RDN_ATTR cercando una corrispondenza con gli attributi dell'autorità di certificazione del certificato. Se il membro pszObjId di CERT_RDN_ATTR è NULL, l'identificatore dell'oggetto attributo viene ignorato. Se il membro dwValueType di CERT_RDN_ATTR viene CERT_RDN_ANY_TYPE, il tipo di valore viene ignorato. Se il membro pbData di CERT_RDN_VALUE_BLOB è NULL, qualsiasi valore corrisponde. Attualmente è supportata solo una corrispondenza esatta con distinzione tra maiuscole e minuscole. Per informazioni sulle opzioni Unicode, vedere Osservazioni. Quando questi valori vengono impostati, la ricerca è limitata ai certificati il cui tipo di codifica corrisponde dwCertEncodingType.
CERT_FIND_ISSUER_NAME	Tipo di dati di pvFindPara: struttura CERT_NAME_BLOB. Cercare un certificato con una corrispondenza esatta dell'intero nome dell'autorità emittente con il nome in CERT_NAME_BLOB La ricerca è limitata ai certificati che corrispondono al dwCertEncodingType.
CERT_FIND_ISSUER_OF	Tipo di dati di pvFindPara: struttura CERT_CONTEXT. Cerca un certificato con un oggetto corrispondente all'emittente in CERT_CONTEXT. Anziché usare CertFindCertificateInStore con questo valore, usare la funzione CertGetCertificateChain .
CERT_FIND_ISSUER_STR	Tipo di dati di pvFindPara: stringa Unicode con terminazione Null. Cerca un certificato contenente la stringa del nome dell'autorità di certificazione specificata. Il membro dell'autorità emittente del certificato viene convertito in una stringa di nome del tipo appropriato usando il formato appropriato di CertNameToStr formattato come CERT_SIMPLE_NAME_STR. Viene quindi eseguita una sottostringa senza distinzione tra maiuscole e minuscole all'interno di una stringa. Quando questo valore viene impostato, la ricerca è limitata ai certificati il cui tipo di codifica corrisponde dwCertEncodingType. Se la corrispondenza della sottostringa ha esito negativo e l'oggetto contiene una stringa con codifica Punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG viene usato per convertire l'oggetto in una stringa Unicode e la corrispondenza della sottostringa viene eseguita di nuovo.
CERT_FIND_KEY_IDENTIFIER	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con una proprietà CERT_KEY_IDENTIFIER_PROP_ID corrispondente all'identificatore di chiave in CRYPT_HASH_BLOB.
CERT_FIND_KEY_SPEC	Tipo di dati di pvFindPara: variabile DWORD che contiene una specifica della chiave. Cerca un certificato con una proprietà CERT_KEY_SPEC_PROP_ID corrispondente alla specifica della chiave in pvFindPara.
CERT_FIND_MD5_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash MD5 corrispondente all'hash in CRYPT_HASH_BLOB.
CERT_FIND_PROPERTY	Tipo di dati di pvFindPara: variabile DWORD contenente un identificatore di proprietà. Cerca un certificato con una proprietà corrispondente all'identificatore di proprietà specificato dal valore DWORD in pvFindPara.
CERT_FIND_PUBLIC_KEY	Tipo di dati di pvFindPara: struttura CERT_PUBLIC_KEY_INFO. Cerca un certificato con una chiave pubblica corrispondente alla chiave pubblica nella struttura CERT_PUBLIC_KEY_INFO.
CERT_FIND_SHA1_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash SHA1 che corrisponde all'hash nella struttura CRYPT_HASH_BLOB.
CERT_FIND_SHA1_SHA256_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash SHA1 + SHA256 corrispondente all'hash nella struttura CRYPT_HASH_BLOB.
CERT_FIND_SHA256_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash SHA256 che corrisponde all'hash nella struttura CRYPT_HASH_BLOB.
CERT_FIND_SIGNATURE_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Cerca un certificato con un hash della firma corrispondente all'hash della firma nella struttura CRYPT_HASH_BLOB.
CERT_FIND_SUBJECT_ATTR	Tipo di dati di pvFindPara: struttura CERT_RDN. Cerca un certificato con attributi oggetto specificati che corrispondono agli attributi nella struttura CERT_RDN. Se vengono impostati valori RDN, la funzione confronta gli attributi dell'oggetto in un certificato con elementi della matrice CERT_RDN_ATTR in questa struttura CERT_RDN. I confronti eseguano l'iterazione degli attributi CERT_RDN_ATTR cercando una corrispondenza con gli attributi dell'oggetto del certificato. Se il membro pszObjId di CERT_RDN_ATTR è NULL, l'identificatore dell'oggetto attributo viene ignorato. Se il membro dwValueType di CERT_RDN_ATTR viene CERT_RDN_ANY_TYPE, il tipo di valore viene ignorato. Se il membro pbData di CERT_RDN_VALUE_BLOB è NULL, qualsiasi valore corrisponde. Attualmente è supportata solo una corrispondenza esatta con distinzione tra maiuscole e minuscole. Per informazioni sulle opzioni Unicode, vedere Osservazioni. Quando questi valori vengono impostati, la ricerca è limitata ai certificati il cui tipo di codifica corrisponde dwCertEncodingType.
CERT_FIND_SUBJECT_CERT	Tipo di dati di pvFindPara: struttura CERT_INFO. Cerca un certificato con un'autorità di certificazione e un numero di serie corrispondente all'emittente e al numero di serie nella struttura CERT_INFO.
CERT_FIND_SUBJECT_NAME	Tipo di dati di pvFindPara: struttura CERT_NAME_BLOB. Cerca un certificato con una corrispondenza esatta dell'intero nome soggetto con il nome nella struttura CERT_NAME_BLOB. La ricerca è limitata ai certificati che corrispondono al valore di dwCertEncodingType.
CERT_FIND_SUBJECT_STR	Tipo di dati di pvFindPara: stringa Unicode con terminazione Null. Cerca un certificato contenente la stringa del nome soggetto specificata. Il membro soggetto del certificato viene convertito in una stringa di nome del tipo appropriato usando il formato appropriato di CertNameToStr formattato come CERT_SIMPLE_NAME_STR. Viene quindi eseguita una sottostringa senza distinzione tra maiuscole e minuscole all'interno di una stringa. Quando questo valore viene impostato, la ricerca è limitata ai certificati il cui tipo di codifica corrisponde dwCertEncodingType.
CERT_FIND_CROSS_CERT_DIST_POINTS	Tipo di dati di pvFindPara: non usato. Trovare un certificato con estensione o proprietà del punto di distribuzione tra certificati.
CERT_FIND_PUBKEY_MD5_HASH	Tipo di dati di pvFindPara: struttura CRYPT_HASH_BLOB. Trovare un certificato la cui chiave pubblica con hash MD5 corrisponde all'hash specificato.

Nota Esistono forme alternative del valore di dwFindType che passano una stringa in pvFindPara. Un modulo usa una stringa Unicode e l'altra una stringa ASCII. I valori che terminano in "_W" o senza un suffisso usano Unicode. I valori che terminano con "_A" usano stringhe ASCII.

[in] pvFindPara

Punta a un elemento di dati o a una struttura utilizzata con dwFindType.

[in] pPrevCertContext

Puntatore all'ultima struttura CERT_CONTEXT restituita da questa funzione. Questo parametro deve essere NULL alla prima chiamata della funzione. Per trovare i certificati successivi che soddisfano i criteri di ricerca, impostare pPrevCertContext sul puntatore restituito dalla chiamata precedente alla funzione. Questa funzione libera i CERT_CONTEXT a cui fa riferimento nonvalori NULL di questo parametro.

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un puntatore a una struttura di sola lettura CERT_CONTEXT.

Se la funzione ha esito negativo e non viene trovato un certificato che corrisponde ai criteri di ricerca, il valore restituito è NULL.

UnNULLCERT_CONTEXT che CertFindCertificateInStore deve essere liberato da CertFreeCertificateContext o passando come parametro pPrevCertContext in una chiamata successiva a CertFindCertificateInStore.

Per informazioni sugli errori estesi, chiamare GetLastError. Di seguito sono riportati alcuni possibili codici di errore.

Codice restituito	Descrizione
CRYPT_E_NOT_FOUND	Non è stato trovato alcun certificato corrispondente ai criteri di ricerca. Ciò può verificarsi se l'archivio è vuoto o viene raggiunta la fine dell'elenco del negozio.
E_INVALIDARG	L'handle nel parametro hCertStore non è uguale a quello nel contesto del certificato a cui punta il parametro pPrevCertContext oppure un valore non valido specificato nel parametro dwFindType.

Osservazioni

Il parametro dwFindFlags viene usato per modificare i criteri di alcuni tipi di ricerca.

Il valore di dwFindFlags CERT_UNICODE_IS_RDN_ATTRS_FLAG viene utilizzato solo con i valori CERT_FIND_SUBJECT_ATTR e CERT_FIND_ISSUER_ATTR per dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG deve essere impostata se la struttura CERT_RDN_ATTR a cui punta pvFindPara è stata inizializzata con stringhe Unicode. Prima di eseguire un confronto, la stringa da confrontare viene convertita usando X509_UNICODE_NAME per fornire confronti Unicode.

I valori dwFindFlags seguenti vengono usati solo con il valore CERT_FIND_ENKEY_USAGE per dwFindType:

è possibile chiamare CertDuplicateCertificateContext per creare un duplicato del contesto restituito. Il contesto restituito può essere aggiunto a un archivio certificati diverso usando CertAddCertificateContextToStoreoppure è possibile aggiungere un collegamento a tale contesto di certificato a un archivio che non è un archivio di raccolta usando CertAddCertificateLinkToStore.

Il puntatore restituito viene liberato quando viene passato come parametro pPrevCertContext in una chiamata successiva alla funzione. In caso contrario, il puntatore deve essere liberato in modo esplicito chiamando CertFreeCertificateContext. Un pPrevCertContext che non è NULL viene sempre liberato da CertFindCertificateInStore usando una chiamata a CertFreeCertificateContext, anche se si verifica un errore nella funzione.

Esempi

L'esempio seguente mostra la ricerca di un contesto di certificato nell'archivio certificati che soddisfa un criterio di ricerca. Per un esempio completo che include il contesto per questo esempio, vedere Programma C di esempio: operazioni dell'archivio certificati.

Per un altro esempio che usa questa funzione, vedere Esempio di programma C: Operazioni dell'archivio certificati di pari livello.

#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);

Fabbisogno

Requisito	Valore
client minimo supportato	Windows XP [app desktop \| App UWP]
server minimo supportato	Windows Server 2003 [app desktop \| App UWP]
piattaforma di destinazione	Finestre
intestazione	wincrypt.h
libreria	Crypt32.lib
dll	Crypt32.dll