Funzione CertGetCertificateChain (wincrypt.h)

Articolo
08/15/2024

La funzione CertGetCertificateChain compila un contesto della catena di certificati a partire da un certificato finale e, se possibile, torna a un certificato radice attendibile.

Sintassi

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

Parametri

[in, optional] hChainEngine

Handle del motore della catena (spazio dei nomi e cache) da usare. Se hChainEngine è NULL, viene usato il motore della catena predefinito HCCE_CURRENT_USER. Questo parametro può essere impostato su HCCE_LOCAL_MACHINE.

[in] pCertContext

Puntatore al CERT_CONTEXT del certificato finale, certificato per il quale viene compilata una catena. Questo contesto di certificato sarà l'elemento zero-index nella prima catena semplice.

[in, optional] pTime

Puntatore a una variabile FILETIME che indica l'ora di convalida della catena. Si noti che l'ora non influisce sull'elenco di attendibilità, la revoca o il controllo dell'archivio radice. L'ora di sistema corrente viene utilizzata se NULL viene passato a questo parametro. L'attendibilità di un determinato certificato come radice attendibile si basa sullo stato corrente dell'archivio radice e non sullo stato dell'archivio radice alla volta passato da questo parametro. Per la revoca, un elenco di revoche di certificati (CRL), deve essere valido al momento corrente. Il valore di questo parametro viene usato per determinare se un certificato elencato in un CRL è stato revocato.

[in] hAdditionalStore

Handle per qualsiasi archivio aggiuntivo in cui cercare i certificati di supporto e elenchi di attendibilità dei certificati (CCL). Questo parametro può essere NULL se non è necessario eseguire ricerche in un archivio aggiuntivo.

[in] pChainPara

Puntatore a una struttura di CERT_CHAIN_PARA che include parametri di compilazione della catena.

[in] dwFlags

Contrassegna i valori che indicano un'elaborazione speciale. Questo parametro può essere una combinazione di uno o più dei flag seguenti.

Valore	Significato
CERT_CHAIN_CACHE_END_CERT `0x00000001`	Quando questo flag è impostato, il certificato finale viene memorizzato nella cache, che potrebbe velocizzare il processo di compilazione della catena. Per impostazione predefinita, il certificato finale non viene memorizzato nella cache e deve essere verificato ogni volta che viene compilata una catena.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY `0x80000000`	Il controllo delle revoche accede solo agli URL memorizzati nella cache. In questo modo si impedisce il recupero di rete di CRL o OCSP per i certificati end o CA. CACHE_ONLY dipende da un amico del computer per aver già recuperato il CRL o OCSP dalla rete.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT `0x04000000`	Questo flag viene usato internamente durante la compilazione della catena per un certificato (OCSP) del protocollo di stato del certificato online per impedire controlli di revoca ciclici. Durante la compilazione della catena, se la risposta OCSP è firmata da un firmatario OCSP indipendente, oltre alla compilazione della catena originale, è presente una seconda catena compilata per il certificato del firmatario OCSP stesso. Questo flag viene usato durante questa seconda compilazione della catena per inibire un certificato del firmatario OCSP indipendente ricorsivo. Se il certificato del firmatario contiene l'estensione szOID_PKIX_OCSP_NOCHECK, il controllo delle revoche viene ignorato per il certificato del firmatario foglia. Sono consentiti sia il controllo OCSP che il controllo CRL. Windows Server 2003 e Windows XP: Questo valore non è supportato.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL `0x00000004`	Usa solo gli URL memorizzati nella cache nella compilazione di una catena di certificati. Internet e Intranet non vengono cercati oggetti basati su URL, ad esempio cab CTL, radici di terze parti e autorità emittenti AIA. La maggior parte delle radici deve trovarsi in una risorsa crypt32.dll. In caso contrario, questo recupero è necessario per evitare un errore di compilazione della catena. Questi cab e radici sono ospitati su server CDN Microsoft ad alte prestazioni. Nota: Questo flag non è applicabile al controllo delle revoche. Impostare CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY per usare solo gli URL memorizzati nella cache per il controllo delle revoche. Normalmente, i cab CTL sono già prelettura tramite il servizio cryptsvc.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING`0x00000040`	Per motivi di prestazioni, il secondo passaggio di compilazione della catena considera solo i possibili percorsi di catena con qualità maggiore o uguale alla massima qualità determinata durante il primo passaggio. Il primo passaggio considera solo la firma valida, la catena completa e le radici attendibili per calcolare la qualità della catena. Questo flag può essere impostato per disabilitare questa ottimizzazione e prendere in considerazione tutti i possibili percorsi di catena durante il secondo passaggio.
CERT_CHAIN_DISABLE_MY_PEER_TRUST `0x00000800`	Questo flag non è supportato. I certificati nell'archivio "My" non vengono mai considerati per l'attendibilità peer.
CERT_CHAIN_ENABLE_PEER_TRUST `0x00000400`	I certificati di entità finali nell'archivio "TrustedPeople" sono attendibili senza eseguire alcuna compilazione della catena. Questa funzione non imposta il CERT_TRUST_IS_PARTIAL_CHAIN o CERT_TRUST_IS_UNTRUSTED_ROOTbit del membro dwErrorStatus del parametro ppChainContext. Windows Server 2003 e Windows XP: Questo flag non è supportato.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE `0x00010000`	L'impostazione di questo flag indica che il chiamante desidera acconsentire esplicitamente a controlli di firma deboli. Questo flag è disponibile nell'aggiornamento cumulativo per ogni sistema operativo a partire da Windows 7 e Windows Server 2008 R2.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS `0x00000080`	L'impostazione predefinita consiste nel restituire solo il percorso della catena di qualità più alta. L'impostazione di questo flag restituirà le catene di qualità inferiori. Questi vengono restituiti nei cLowerQualityChainContext e rgpLowerQualityChainContext campi del contesto della catena.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE `0x00000100`	L'impostazione di questo flag impedisce l'aggiornamento automatico delle radici di terze parti dal server Web di Windows Update.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT `0x08000000`	Quando si imposta CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT e si specifica anche un valore per il dwUrlRetrievalTimeout membro della struttura CERT_CHAIN_PARA, il valore specificato in dwUrlRetrievalTimeout rappresenta il timeout cumulativo in tutti i recupero url di revoca. Se si imposta CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT ma non si specifica un valore dwUrlRetrievalTimeout, per impostazione predefinita viene impostato il timeout cumulativo massimo su 20 secondi. Ogni URL testato eseguirà il timeout dopo il superamento della metà del saldo cumulativo rimanente. Vale a dire, il primo URL si verifica dopo 10 secondi, il secondo dopo 5 secondi, il terzo dopo 2,5 secondi e così via fino a quando non viene completato un URL, 20 secondi o non sono presenti altri URL da testare. Se non si imposta CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT, a ogni URL di revoca nella catena viene assegnato un timeout massimo uguale al valore specificato in dwUrlRetrievalTimeout. Se non si specifica un valore per il membro dwUrlRetrievalTimeout, a ogni URL di revoca viene assegnato un timeout predefinito massimo di 15 secondi. Se nessun URL ha esito positivo, il valore di timeout cumulativo massimo è di 15 secondi moltiplicato per il numero di URL nella catena. È possibile impostare i valori predefiniti usando Criteri di gruppo.
CERT_CHAIN_TIMESTAMP_TIME `0x00000200`	Quando questo flag è impostato, pTime viene usato come timestamp per determinare se il certificato finale è stato valido. L'ora corrente può essere usata anche per determinare se il certificato finale rimane valido. Tutte le altre autorità di certificazione (CA) e i certificati radice nella catena vengono controllati usando l'ora corrente e non pTime .
CERT_CHAIN_DISABLE_AIA `0x00002000`	L'impostazione di questo flag disattiva in modo esplicito i recupero dell'accesso alle informazioni sull'autorità (AIA). A volte i server TLS non sono configurati correttamente e non includono i certificati CA corretti nell'handshake.

È anche possibile impostare i flag di revoca seguenti, ma è possibile impostare un solo flag di questo gruppo alla volta.

Valore	Significato
CERT_CHAIN_REVOCATION_CHECK_END_CERT `0x10000000`	Il controllo delle revoche viene eseguito sul certificato finale e solo sul certificato finale.
CERT_CHAIN_REVOCATION_CHECK_CHAIN `0x20000000`	Il controllo delle revoche viene eseguito su tutti i certificati in ogni catena.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT `0x40000000`	Il controllo delle revoche viene eseguito su tutti i certificati in tutte le catene, ad eccezione del certificato radice.

[in] pvReserved

Questo parametro è riservato e deve essere NULL.

[out] ppChainContext

Indirizzo di un puntatore al contesto della catena creato. Al termine dell'uso del contesto della catena, rilasciare la catena chiamando la funzione CertFreeCertificateChain .

Valore restituito

Se la funzione ha esito positivo, la funzione restituisce un valore diverso da zero (TRUE).

Se la funzione ha esito negativo, restituisce zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError.

Osservazioni

Quando un'applicazione richiede una catena di certificati, la struttura restituita è sotto forma di CERT_CHAIN_CONTEXT. Questo contesto contiene una matrice di strutture CERT_SIMPLE_CHAIN in cui ogni catena semplice passa da un certificato finale a un certificato autofirmato. Il contesto della catena connette catene semplici tramite elenchi di attendibilità. Ogni catena semplice contiene la catena di certificati, informazioni di attendibilità di riepilogo sulla catena e informazioni di attendibilità su ogni elemento certificato nella catena.

Le osservazioni seguenti si applicano al controllo della firma avanzata:

È possibile abilitare il controllo delle firme complesse per questa funzione impostando il membro pStrongSignPara della struttura CERT_CHAIN_PARA a cui punta il parametro pChainPara.
Se nella catena viene trovato un certificato senza firma complessa, gli errori di CERT_TRUST_HAS_WEAK_SIGNATURE e CERT_TRUST_IS_NOT_SIGNATURE_VALID vengono impostati nel campo dwErrorStatus della struttura CERT_TRUST_STATUS. Il parametro ppChainContext punta a una struttura CERT_CHAIN_CONTEXT che, a sua volta, punta alla struttura CERT_TRUST_STATUS.
Se la catena è firmata con firma avanzata, viene verificata la chiave pubblica nel certificato finale per determinare se soddisfa i requisiti minimi di lunghezza della chiave pubblica per una firma complessa. Se la condizione non viene soddisfatta, i CERT_TRUST_HAS_WEAK_SIGNATURE e gli errori di CERT_TRUST_IS_NOT_SIGNATURE_VALID vengono impostati nel campo dwErrorStatus della struttura CERT_TRUST_STATUS. Per disabilitare il controllo della lunghezza della chiave, impostare il valore CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG nel dwStrongSignFlags membro della struttura CERT_CHAIN_PARA a cui punta il parametro pChainPara.
Se i flag CERT_STRONG_SIGN_ENABLE_CRL_CHECK o CERT_STRONG_SIGN_ENABLE_OCSP_CHECK vengono impostati nella struttura CERT_STRONG_SIGN_SERIALIZED_INFO e viene trovata una risposta CRL o OCSP senza firma avanzata, la risposta CRL o OCSP verrà considerata offline. Ovvero, gli errori di CERT_TRUST_IS_OFFLINE_REVOCATION e CERT_TRUST_REVOCATION_STATUS_UNKNOWN vengono impostati nel campo dwErrorStatus della struttura CERT_TRUST_STATUS. Inoltre, il membro dwRevocationResult della struttura CERT_REVOCATION_INFO è impostato su NTE_BAD_ALGID.

Le raccomandazioni seguenti si applicano a qualsiasi applicazione Windows che chiama queste API per verificare un certificato di autenticazione del server TLS:

Abilitare solo il controllo delle revoche per il certificato finale.
- Impostare CERT_CHAIN_REVOCATION_CHECK_END_CERT flag.
- La maggior parte dei certificati DELLA CA ha una validità di tempo da 1 a 6 mesi.
  - Poiché i CRL scaricati vengono memorizzati nella cache, questa validità è troppo lunga per avere molto valore.
- In caso di compromissione della CA, anche i certificati verrebbero aggiunti al CTL non consentito di Windows
- La procedura consigliata per i server TLS consiste nel supportare l'associazione OCSP per il certificato finale.
  - In tal caso, non sarà necessario alcun recupero di rete, a meno che la risposta OCSP graffata sia scaduta.
Abilitare il recupero di rete per CTL, OCSP, autorità emittenti AIA e cab CTL della piattaforma Windows e radici di terze parti.
- Quando il CERT_CHAIN_REVOCATION_CHECK_END_CERT precedente è impostato, si tratta dell'impostazione predefinita.
- Non impostare alcuno dei flag seguenti per impedire il recupero di rete. Per altre informazioni su questi flag, vedere la tabella dwFlags
  precedente:
  - CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
  - CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
  - CERT_CHAIN_DISABLE_AIA
Abilitare il timeout cumulativo per il recupero di rete CRL e OCSP.
- Impostare il flag di CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT passato a CertGetCertificateChain.
- Fornisce un limite massimo per il tempo totale consentito per il recupero di rete CRL e OCSP.
Ridurre il tempo massimo consentito per ogni recupero di rete da 15 a 10 secondi.
- Impostare il campo dwUrlRetrievalTimeout nel CERT_CHAIN_PARA passato a CertGetCertificateChain su 10 * 1000 millisecondi.
- Ciò riduce anche il timeout accumulativo da 20 a 10 secondi.
  - Solo le risposte OCSP devono essere scaricate per i certificati finali. 5 secondi devono essere sufficienti per il download.
Ignorare gli errori di revoca offline.
- Impostare CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS nel CERT_CHAIN_POLICY_PARA passato a CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL).
- Il recupero di rete di OCSP e CRL è il tentativo migliore. La maggior parte dei recupero di rete dovrebbe avere esito positivo in un paio di secondi, ma non è garantito 100%.
Informazioni di convalida del certificato finale della cache.
- Impostare il CERT_CHAIN_CACHE_END_CERT.
  - Abilita la memorizzazione nella cache delle informazioni sui certificati finali oltre ai certificati intermedi.
- È comune stabilire più connessioni TLS allo stesso server.

Esempi

Per un esempio che usa questa funzione, vedere Programma C di esempio: Creazione di una catena di certificati.

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

Vedere anche

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

funzioni di verifica della catena di certificati

Condividi tramite