Funzione CertGetCertificateChain (wincrypt.h)

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.

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

[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

Vedere anche

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

funzioni di verifica della catena di certificati