Funzione CertFindCertificateInStore (wincrypt.h)
La funzione CertFindCertificateInStore trova il contesto del certificato primo o successivo in un archivio certificati che corrisponde a un criterio di ricerca stabilito dal dwFindType e dal relativo pvFindPara associato. 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. I tipi di codifica del certificato e dei messaggi devono essere specificati combinandoli con un'operazione OR 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 eseguita. Il tipo di ricerca determina il tipo di dati, il contenuto e l'uso di pvFindPara. Questo parametro può avere uno dei valori seguenti.
| Valore | Significato |
|---|---|
|
Tipo di dati 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.
|
|
Tipo di dati pvFindPara: struttura CERT_ID .
Trovare il certificato identificato dal CERT_ID specificato. |
|
Tipo di dati pvFindPara: struttura CTL_USAGE .
Cerca un certificato con estensione szOID_ENHANCED_KEY_USAGE o un CERT_CTL_PROP_ID corrispondente al membro pszUsageIdentifier della struttura CTL_USAGE . |
|
Tipo di dati pvFindPara: struttura CERT_ENHKEY_USAGE .
Cerca un certificato nell'archivio con un'estensione di utilizzo chiave avanzata o una proprietà di utilizzo chiave avanzata e un identificatore di utilizzo corrispondente al membro cUsageIdentifier nella struttura CERT_ENHKEY_USAGE . Un certificato ha un'estensione avanzata per l'utilizzo delle chiavi se ha una struttura CERT_EXTENSION con il membro pszObjId impostato su szOID_ENHANCED_KEY_USAGE. Un certificato ha una proprietà di utilizzo chiave avanzata se è impostato il relativo identificatore di 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. |
|
Tipo di dati pvFindPara: struttura CERT_CONTEXT .
Cerca un certificato che corrisponde esattamente al contesto del certificato specificato. |
|
Tipo di dati pvFindPara: struttura CRYPT_HASH_BLOB .
Cerca un certificato con un hash SHA1 corrispondente all'hash nella struttura CRYPT_HASH_BLOB . |
|
Tipo di dati 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.
|
|
Tipo di dati pvFindPara: struttura CERT_RDN .
Cerca un certificato con gli 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 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 è CERT_RDN_ANY_TYPE, il tipo di valore viene ignorato. Se il membro pbData di CERT_RDN_VALUE_BLOB è NULL, qualsiasi valore corrisponde a . 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 a dwCertEncodingType. |
|
Tipo di dati 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 a dwCertEncodingType. |
|
Tipo di dati 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 . |
|
Tipo di dati 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 a dwCertEncodingType. Se la corrispondenza della sottostringa ha esito negativo e l'oggetto contiene un RDN di posta elettronica con stringa codificata punycode, CERT_NAME_STR_ENABLE_PUNYCODE_FLAG viene usato per convertire l'oggetto in una stringa Unicode e la corrispondenza di sottostringa viene eseguita di nuovo. |
|
Tipo di dati 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. |
|
Tipo di dati 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. |
|
Tipo di dati pvFindPara: struttura CRYPT_HASH_BLOB .
Cerca un certificato con un hash MD5 corrispondente all'hash in CRYPT_HASH_BLOB. |
|
Tipo di dati di pvFindPara: variabile DWORD che contiene un identificatore di proprietà.
Cerca un certificato con una proprietà corrispondente all'identificatore di proprietà specificato dal valore DWORD in pvFindPara. |
|
Tipo di dati pvFindPara: struttura CERT_PUBLIC_KEY_INFO .
Cerca un certificato con una chiave pubblica corrispondente alla chiave pubblica nella struttura CERT_PUBLIC_KEY_INFO . |
|
Tipo di dati pvFindPara: struttura CRYPT_HASH_BLOB .
Cerca un certificato con un hash SHA1 corrispondente all'hash nella struttura CRYPT_HASH_BLOB . |
|
Tipo di dati pvFindPara: struttura CRYPT_HASH_BLOB .
Cerca un certificato con un hash della firma corrispondente all'hash della firma nella struttura CRYPT_HASH_BLOB . |
|
Tipo di dati pvFindPara: struttura CERT_RDN .
Cerca un certificato con gli attributi del soggetto specificati che corrispondono agli attributi nella struttura CERT_RDN . Se vengono impostati valori RDN, la funzione confronta gli attributi del soggetto 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 alla ricerca di una corrispondenza con gli attributi del soggetto 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 è CERT_RDN_ANY_TYPE, il tipo di valore viene ignorato. Se il membro pbData di CERT_RDN_VALUE_BLOB è NULL, qualsiasi valore corrisponde a . 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 a dwCertEncodingType. |
|
Tipo di dati pvFindPara: struttura CERT_INFO .
Cerca un certificato con un emittente e un numero di serie che corrispondono all'emittente e al numero di serie nella struttura CERT_INFO . |
|
Tipo di dati pvFindPara: struttura CERT_NAME_BLOB .
Cerca un certificato con una corrispondenza esatta dell'intero nome del soggetto con il nome nella struttura CERT_NAME_BLOB . La ricerca è limitata ai certificati che corrispondono al valore di dwCertEncodingType. |
|
Tipo di dati pvFindPara: stringa Unicode con terminazione Null.
Cerca un certificato contenente la stringa del nome del 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 a dwCertEncodingType. |
|
Tipo di dati pvFindPara: non usato.
Trovare un certificato con estensione o proprietà del punto di distribuzione tra certificati. |
|
Tipo di dati pvFindPara: struttura CRYPT_HASH_BLOB .
Trovare un certificato la cui chiave pubblica con hash MD5 corrisponde all'hash specificato. |
[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 nella 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 il CERT_CONTEXT a cui fa riferimento i valori non 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.
Un CERT_CONTEXT non NULL restituito da CertFindCertificateInStore deve essere liberato da CertFreeCertificateContext o passando come parametro pPrevCertContext su una chiamata successiva a CertFindCertificateInStore.
Per informazioni sugli errori estesi, chiamare GetLastError. Di seguito sono riportati alcuni possibili codici di errore.
| Codice restituito | Descrizione |
|---|---|
|
Non è stato trovato alcun certificato corrispondente ai criteri di ricerca. Ciò può verificarsi se l'archivio è vuoto o se viene raggiunta la fine dell'elenco del negozio. |
|
L'handle nel parametro hCertStore non corrisponde a quello nel contesto del certificato a cui punta il parametro pPrevCertContext oppure un valore non valido specificato nel parametro dwFindType . |
Commenti
Il parametro dwFindFlags viene usato per modificare i criteri di alcuni tipi di ricerca.
Il valore CERT_UNICODE_IS_RDN_ATTRS_FLAG dwFindFlags viene usato solo con i valori CERT_FIND_SUBJECT_ATTR e CERT_FIND_ISSUER_ATTR per dwFindType. CERT_UNICODE_IS_RDN_ATTRS_FLAG deve essere impostato 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:
CertDuplicateCertificateContext può essere chiamato per creare un duplicato del contesto restituito. Il contesto restituito può essere aggiunto a un archivio certificati diverso usando CertAddCertificateContextToStore oppure è 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.
Esempio
Nell'esempio seguente viene illustrato come trovare 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 Esempio di programma C: operazioni dell'archivio certificati.
Per un altro esempio che usa questa funzione, vedere Esempio di programma C: operazioni di raccolta e 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);
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2003 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | wincrypt.h |
| Libreria | Crypt32.lib |
| DLL | Crypt32.dll |
Vedi anche
CertAddCertificateContextToStore
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per