Funzione CertGetCertificateChain (wincrypt.h)
La funzione CertGetCertificateChain crea 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, il 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 è basata 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), stesso, deve essere valido al momento corrente. Il valore di questo parametro viene usato per determinare se è stato revocato un certificato elencato in un CRL.
[in] hAdditionalStore
Handle per qualsiasi archivio aggiuntivo in cui cercare i certificati di supporto e gli elenchi di attendibilità dei certificati . Questo parametro può essere NULL se non è necessario eseguire ricerche in un archivio aggiuntivo.
[in] pChainPara
Puntatore a una struttura 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 |
|---|---|
|
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. |
|
Il controllo della revoca accede solo agli URL memorizzati nella cache. |
|
Questo flag viene usato internamente durante la compilazione della catena per un certificato di firma OCSP ( Online Certificate Status Protocol ) per evitare 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 di firma 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. |
|
Usa solo gli URL memorizzati nella cache nella compilazione di una catena di certificati. Internet e Intranet non vengono cercati oggetti basati su URL.
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. |
|
Per motivi di prestazioni, il secondo passaggio di compilazione della catena considera solo i percorsi di catena potenziali 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 percorsi potenziali della catena durante il secondo passaggio. |
|
Questo flag non è supportato. I certificati nell'archivio "My" non vengono mai considerati per l'attendibilità peer. |
|
I certificati dell'entità finale nell'archivio "TrustedPeople" sono attendibili senza eseguire alcuna compilazione della catena. Questa funzione non imposta i bit del membro CERT_TRUST_IS_PARTIAL_CHAIN o CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus del parametro ppChainContext . Windows Server 2003 Windows XP : Questo flag non è supportato. |
|
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. |
|
L'impostazione predefinita consiste nel restituire solo il percorso della catena di qualità più elevata. L'impostazione di questo flag restituirà le catene di qualità inferiori. Questi vengono restituiti nei campi cLowerQualityChainContext e rgpLowerQualityChainContext del contesto della catena. |
|
L'impostazione di questo flag impedisce l'aggiornamento automatico delle radici di terze parti dal server Web Windows Update. |
|
Quando si imposta CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT e si specifica anche un valore per il membro dwUrlRetrievalTimeout 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 , il timeout cumulativo massimo viene impostato, per impostazione predefinita, su 20 secondi. Ogni URL testato timeout dopo il superamento della metà del saldo cumulativo rimanente. Ovvero, 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 un URL non riesce, 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. |
|
Quando questo flag è impostato, pTime viene usato come ora di 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. |
|
L'impostazione di questo flag disattiva in modo esplicito i recupero di AIA (Authority Information Access). |
È 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 non riesce, restituisce zero (FALSE). Per informazioni sugli errori estesi, chiamare GetLastError.
Commenti
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 è 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, gli errori CERT_TRUST_HAS_WEAK_SIGNATURE e 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 membro dwStrongSignFlags 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 complessa, 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.
Esempio
Per un esempio che usa questa funzione, vedere Esempio di programma C: Creazione di una catena di certificati.
Requisiti
| 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
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