Funzione CertFindChainInStore (wincrypt.h)

Articolo
07/16/2024

La funzione CertFindChainInStore trova il primo o il certificato successivo in un archivio che soddisfa i criteri specificati. Compila e verifica quindi un contesto della catena di certificati per tale certificato. Il certificato trovato e per il quale viene compilata la catena viene selezionato in base ai criteri stabiliti dai parametri dwFindFlags, dwFindTypee parametri pvFindPara. Questa funzione può essere usata in un ciclo per trovare tutti i certificati in un archivio certificati che corrispondono ai criteri di ricerca specificati e per compilare un contesto della catena di certificati per ogni certificato trovato.

Sintassi

PCCERT_CHAIN_CONTEXT CertFindChainInStore(
  [in] HCERTSTORE           hCertStore,
  [in] DWORD                dwCertEncodingType,
  [in] DWORD                dwFindFlags,
  [in] DWORD                dwFindType,
  [in] const void           *pvFindPara,
  [in] PCCERT_CHAIN_CONTEXT pPrevChainContext
);

Parametri

[in] hCertStore

Handle dell'archivio in cui cercare un certificato in cui viene compilata una catena. Questo handle viene passato come archivio aggiuntivo al funzione CertGetCertificateChain durante la compilazione della catena.

[in] dwCertEncodingType

Il tipo di codifica del certificato usato per codificare l'archivio. Il tipo di codifica messaggio identificatore, contenuto nell' word elevato di questo valore, viene ignorato da questa funzione.

Questo parametro può essere il tipo di codifica del certificato attualmente definito seguente.

Valore	Significato
X509_ASN_ENCODING 1 (0x1)	Specifica la codifica del certificato X.509.

[in] dwFindFlags

Contiene opzioni aggiuntive per la ricerca. I valori possibili per questo parametro dipendono dal valore del parametro dwFindType.

Questo parametro può contenere zero o una combinazione di uno o più dei valori seguenti quando dwFindType contiene CERT_CHAIN_FIND_BY_ISSUER.

Valore	Significato
CERT_CHAIN_FIND_BY_ISSUER_COMPARE_KEY_FLAG	Confronta la chiave pubblica nel certificato con l'chiave pubblica del provider di servizi di crittografia. Questo confronto è l'ultimo controllo eseguito sulla catena al momento della compilazione. Poiché il hCryptProv membro di un'autorità emittente contiene una chiave privata, potrebbe essere necessario controllare più volte durante questo processo; per facilitare questo controllo, è possibile impostare il membro dwAcquirePrivateKeyFlags nella struttura CERT_CHAIN_FIND_BY_ISSUER_PARA per abilitare la memorizzazione nella cache di tale hCryptProv.
CERT_CHAIN_FIND_BY_ISSUER_COMPLEX_CHAIN_FLAG	Per impostazione predefinita, viene verificata solo la prima catena semplice per verificare la corrispondenza del nome dell'autorità emittente. Con questo flag impostato, viene eseguito l'override del valore predefinito e vengono controllate anche le successive catene semplici per verificare la corrispondenza del nome dell'autorità emittente.
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_FLAG	Migliora le prestazioni di questa funzione causando la ricerca solo negli archivi di sistema memorizzati nella cache (Root, My, Ca, Trust) per trovare i certificati dell'autorità di certificazione. Se questo flag non è impostato, la funzione cerca negli archivi di sistema memorizzati nella cache e nell'archivio rappresentato dal parametro hCertStore .
CERT_CHAIN_FIND_BY_ISSUER_CACHE_ONLY_URL_FLAG	Viene eseguita la ricerca solo nella cache URL. Internet non viene cercato.
CERT_CHAIN_FIND_BY_ISSUER_LOCAL_MACHINE_FLAG	Apre solo gli archivi certificati del computer locale. Gli archivi certificati dell'utente corrente non vengono aperti.
CERT_CHAIN_FIND_BY_ISSUER_NO_KEY_FLAG	Non viene effettuato alcun controllo per determinare se il certificato ha una chiave privata associata.

[in] dwFindType

Determina i criteri da usare per trovare un certificato nell'archivio.

Questo parametro può essere il valore attualmente definito seguente.

CERT_CHAIN_FIND_BY_ISSUER

Trova il certificato in base al nome dell'emittente. Il parametro pvFindPara è un puntatore a una struttura CERT_CHAIN_FIND_BY_ISSUER_PARA che contiene membri che modificano la ricerca.

La catena di certificati viene compilata per un certificato con una chiave privata disponibile . Per impostazione predefinita, solo le autorità emittenti nella prima catena semplice vengono confrontate con un nome dell'autorità emittente. Se questo flag è impostato, tutte le catene vengono controllate per un certificato dell'autorità emittente corrispondente a uno dei nomi di un'autorità emittente.

Questa funzione confronta il nome BLOB passati nella struttura pvFindPara a qualsiasi autorità di certificazione (CA) nella catena, non solo all'autorità di certificazione nel certificato radice.

Questa funzione non esegue alcun controllo di revoca.

Se pPrevChainContext non è NULL, questa funzione restituirà una catena per un certificato diverso ogni volta che viene chiamata la funzione. Se è presente un solo certificato appropriato, ma esistono due autorità di certificazione emittente corrispondenti, una delle quali viene revocata, è possibile che questa funzione restituisca la catena revocata. Se l'applicazione verifica la revoca stessa tramite chiamate alla funzione CertVerifyRevocation e trova la catena non adatta, una chiamata aggiuntiva alla funzione CertFindChainInStore non restituirà una catena che include lo stesso certificato dell'autorità di certificazione valida. Restituisce invece una catena completamente diversa con un certificato diverso o NULL, se non è possibile trovare tale catena.

[in] pvFindPara

Puntatore che contiene criteri di ricerca aggiuntivi. Il tipo e il formato dei dati a cui punta questo parametro dipende dal valore del parametro dwFindType.

[in] pPrevChainContext

Puntatore a una struttura CERT_CHAIN_CONTEXT restituita da una chiamata precedente a questa funzione. La ricerca viene avviata da questo certificato. Per la prima chiamata a questa funzione, questo parametro deve essere NULL. Nelle chiamate successive, è il puntatore restituito dalla chiamata precedente alla funzione . Se questo parametro non è NULL, questa funzione libera questa struttura.

Valore restituito

Se il contesto della prima o della catena successiva non viene compilato, viene restituito NULL. In caso contrario, viene restituito un puntatore a una struttura di sola lettura CERT_CHAIN_CONTEXT. La struttura CERT_CHAIN_CONTEXT viene liberata quando viene passata come parametro pPrevChainContext su una chiamata successiva a questa funzione. In caso contrario, la struttura CERT_CHAIN_CONTEXT deve essere liberata in modo esplicito chiamando la funzione CertFreeCertificateChain .

Osservazioni

Il parametro pPrevChainContext deve essere NULL nella prima chiamata per compilare il contesto della catena. Per compilare il contesto della catena successiva, la pPrevChainContext viene impostata sulla struttura CERT_CHAIN_CONTEXT restituita da una chiamata precedente. Se pPrevChainContext non è NULL, la struttura viene sempre liberata da questa funzione usando la funzione CertFreeCertificateChain, anche se si verifica un errore.

Fabbisogno

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