Funzione CertVerifyCertificateChainPolicy (wincrypt.h)

Articolo
08/15/2024

La funzione CertVerifyCertificateChainPolicy controlla una catena di certificati per verificarne la validità, inclusa la conformità con i criteri di validità specificati.

Sintassi

BOOL CertVerifyCertificateChainPolicy(
  [in]      LPCSTR                    pszPolicyOID,
  [in]      PCCERT_CHAIN_CONTEXT      pChainContext,
  [in]      PCERT_CHAIN_POLICY_PARA   pPolicyPara,
  [in, out] PCERT_CHAIN_POLICY_STATUS pPolicyStatus
);

Parametri

[in] pszPolicyOID

Le strutture dei criteri della catena di verifica predefinite correnti sono elencate nella tabella seguente.

Valore	Significato
CERT_CHAIN_POLICY_BASE (LPCSTR) 1	Implementa i controlli di verifica dei criteri della catena di base. Il dwFlags membro della struttura a cui punta pPolicyPara può essere impostato per modificare il comportamento di controllo dei criteri predefinito.
CERT_CHAIN_POLICY_AUTHENTICODE (LPCSTR) 2	Implementa i controlli di verifica dei criteri della catena Authenticode. Il membro pvExtraPolicyPara della struttura a cui punta pPolicyPara può essere impostato in modo che punti a una struttura AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_PARA. È possibile impostare membro pvExtraPolicyStatus della struttura a cui punta pPolicyStatus in modo che punti a una struttura AUTHENTICODE_EXTRA_CERT_CHAIN_POLICY_STATUS.
CERT_CHAIN_POLICY_AUTHENTICODE_TS (LPCSTR) 3	Implementa i controlli di verifica dei criteri della catena timestamp Authenticode. È possibile impostare membro pvExtraPolicyPara della struttura di dati a cui punta pPolicyPara in modo che punti a una struttura AUTHENTICODE_TS_EXTRA_CERT_CHAIN_POLICY_PARA. Il membro pvExtraPolicyStatus della struttura dei dati a cui punta pPolicyStatus non viene utilizzato e deve essere impostato su `NULL`.
CERT_CHAIN_POLICY_SSL (LPCSTR) 4	Implementa i controlli di verifica dei criteri di catena client/server SSL. È possibile impostare membro pvExtraPolicyPara nella struttura dei dati a cui punta pPolicyPara in modo che punti a una struttura SSL_EXTRA_CERT_CHAIN_POLICY_PARA inizializzata con criteri aggiuntivi. Nota: Per distinguere i certificati di autorizzazione client e server, la chiamata alla funzione CertGetCertificateChain per ottenere il contesto della catena deve specificare il tipo di certificato impostando l'utilizzo previsto. Impostare l'utilizzo previsto impostando il membro RequestedUsage della struttura CERT_CHAIN_PARA passata nel parametro di input pChainPara della funzione CertGetCertificateChain.
CERT_CHAIN_POLICY_BASIC_CONSTRAINTS (LPCSTR) 5	Implementa i criteri della catena di vincoli di base. Scorre tutti i certificati nel controllo della catena per un szOID_BASIC_CONSTRAINTS o un'estensione szOID_BASIC_CONSTRAINTS2. Se nessuna delle estensioni è presente, si presuppone che il certificato disponga di criteri validi. In caso contrario, per il primo elemento del certificato, controlla se corrisponde al CA_FLAG previsto o END_ENTITY_FLAG specificato nel dwFlags membro della struttura CERT_CHAIN_POLICY_PARA a cui punta il parametro pPolicyPara. Se nessuno o entrambi i flag sono impostati, il primo elemento può essere una CA o END_ENTITY. Tutti gli altri elementi devono essere un'autorità di certificazione (CA). Se PathLenConstraint è presente nell'estensione, viene controllato. I primi elementi nelle catene semplici rimanenti( ovvero i certificati usati per firmare il CTL) vengono controllati per essere un END_ENTITY. Se la verifica non riesce, dwError verrà impostata su TRUST_E_BASIC_CONSTRAINTS.
CERT_CHAIN_POLICY_NT_AUTH (LPCSTR) 6	Implementa i criteri della catena di autenticazione di Windows NT, costituiti da tre verifiche di catena distinte nell'ordine seguente: - CERT_CHAIN_POLICY_BASE: implementa i controlli di verifica dei criteri della catena di base. La LOWORD di dwFlags può essere impostata in pPolicyPara per modificare il comportamento di controllo dei criteri predefinito. Per altre informazioni, vedere CERT_CHAIN_POLICY_BASE. - CERT_CHAIN_POLICY_BASIC_CONSTRAINTS: implementa i criteri della catena di vincoli di base. È possibile impostare hiWORD di dwFlags per specificare se il primo elemento deve essere una CA o END_ENTITY. Per altre informazioni, vedere CERT_CHAIN_POLICY_BASIC_CONSTRAINTS. - Controlla se il secondo elemento della catena, la CA che ha emesso il certificato finale, è una CA attendibile per l'autenticazione di Windows NT. Un'autorità di certificazione viene considerata attendibile se esiste nell'archivio del Registro di sistema "NTAuth" presente nel percorso dell'archivio CERT_SYSTEM_STORE_LOCAL_MACHINE_ENTERPRISE. Se la verifica ha esito negativo, la CA non è attendibile e dwError è impostata su CERT_E_UNTRUSTEDCA. Se CERT_PROT_ROOT_DISABLE_NT_AUTH_REQUIRED_FLAG è impostato nel valore flag del criterio HKEY_LOCAL_MACHINE ProtectedRoots sottochiave, definito da CERT_PROT_ROOT_FLAGS_REGPATH e il controllo precedente ha esito negativo, la catena viene controllata per CERT_TRUST_HAS_VALID_NAME_CONSTRAINTS impostata in dwInfoStatus. Questa impostazione viene impostata se è presente un vincolo di nome valido per tutti gli spazi dei nomi, incluso l'UPN. Se la catena non dispone di questo set di informazioni, dwError è impostato su CERT_E_UNTRUSTEDCA.
CERT_CHAIN_POLICY_MICROSOFT_ROOT (LPCSTR) 7	Controlla l'ultimo elemento della prima catena semplice per ottenere una chiave pubblica radice Microsoft. Se tale elemento non contiene una chiave pubblica radice Microsoft, il membro dwError della struttura CERT_CHAIN_POLICY_STATUS a cui punta il parametro pPolicyStatus è impostato su CERT_E_UNTRUSTEDROOT. Il dwFlags membro della struttura CERT_CHAIN_POLICY_PARA a cui punta il parametro pPolicyStatus può contenere il flag MICROSOFT_ROOT_CERT_CHAIN_POLICY_CHECK_APPLICATION_ROOT_FLAG, che fa sì che questa funzione controlli la radice dell'applicazione Microsoft "Microsoft Root Certificate Authority 2011". Il dwFlags membro della struttura CERT_CHAIN_POLICY_PARA a cui punta il parametro pPolicyPara può contenere il flag MICROSOFT_ROOT_CERT_CHAIN_POLICY_ENABLE_TEST_ROOT_FLAG, che fa sì che questa funzione verifichi anche la presenza delle radici di test Microsoft. Nota: Questo criterio identificatore di oggetto (OID) non esegue alcun controllo di verifica dei criteri da solo, ma deve essere usato insieme ad altri criteri.
CERT_CHAIN_POLICY_EV (LPCSTR) 8	Specifica che viene eseguita la convalida estesa dei certificati. Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Questo valore non è supportato.
CERT_CHAIN_POLICY_SSL_F12 (LPCSTR) 9	Controlla se i certificati nella catena hanno crittografia debole o se la conformità del certificato radice di terze parti e specifica una stringa di errore. Il pvExtraPolicyStatus membro della struttura CERT_CHAIN_POLICY_STATUS a cui punta il parametro pPolicyStatus deve puntare a SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS, che viene aggiornato con i risultati dei controlli di conformità del programma radice e crypto debole. Prima di chiamare, il membro cbSize della struttura CERT_CHAIN_POLICY_STATUS a cui punta il parametro pPolicyStatus deve essere impostato su un valore maggiore o uguale a sizeof(SSL_F12_EXTRA_CERT_CHAIN_POLICY_STATUS). Il membro dwError nella struttura CERT_CHAIN_POLICY_STATUS a cui punta il parametro pPolicyStatus verrà impostato su TRUST_E_CERT_SIGNATURE per potenziali crypto deboli e impostato su CERT_E_UNTRUSTEDROOT per radici di terze parti non conformi al programma radice Microsoft. Windows 10, versione 1607, Windows Server 2016, Windows 10, versione 1511 con KB3172985, Windows 10 RTM con KB3163912, Windows 8.1 e Windows Server 2012 R2 con KB3163912 e Windows 7 con SP1 e Windows Server 2008 R2 SP1 con KB3161029

[in] pChainContext

Puntatore a una struttura CERT_CHAIN_CONTEXT che contiene una catena da verificare.

[in] pPolicyPara

Puntatore a una struttura CERT_CHAIN_POLICY_PARA che fornisce i criteri di verifica dei criteri per la catena. Il dwFlags membro di tale struttura può essere impostato per modificare il comportamento di controllo dei criteri predefinito.

Inoltre, i parametri specifici dei criteri possono essere passati anche nel membro pvExtraPolicyPara della struttura.

[in, out] pPolicyStatus

Puntatore a una struttura CERT_CHAIN_POLICY_STATUS in cui vengono restituite informazioni sullo stato della catena. Lo stato aggiuntivo specifico dell'OID può essere restituito nel membro pvExtraPolicyStatus di questa struttura.

Valore restituito

Il valore restituito indica se la funzione è stata in grado di verificare la presenza dei criteri, non indica se il controllo dei criteri non è riuscito o è stato superato.

Se è possibile verificare la catena per i criteri specificati, viene restituito e viene aggiornato il membro dwError del pPolicyStatus. Un dwError di 0 (ERROR_SUCCESS o S_OK) indica che la catena soddisfa i criteri specificati.

Se la catena non può essere convalidata, il valore restituito è TRUE ed è necessario verificare il parametro pPolicyStatus per l'errore effettivo.

Un valore di FALSE indica che la funzione non è stata in grado di verificare la presenza dei criteri.

Osservazioni

Un membro dwError della struttura CERT_CHAIN_POLICY_STATUS a cui punta pPolicyStatus può essere applicato a un singolo elemento della catena, a una catena semplice o a un intero contesto di catena. Se dwError si applica all'intero contesto della catena, sia l' lChainIndex che i membri lElementIndex della struttura CERT_CHAIN_POLICY_STATUS vengono impostati su . Se dwError si applica a una catena semplice completa, lElementIndex è impostato su –1 e lChainIndex viene impostato sull'indice della prima catena con un errore. Se dwError si applica a un singolo elemento certificato, lChainIndex e lElementIndex indicizzare il primo certificato con l'errore.

Per ottenere l'elemento del certificato, usare questa sintassi:

pChainContext->rgpChain[lChainIndex]->rgpElement[lElementIndex];

Usare la funzione CertGetCertificateChain per abilitare ed eseguire il controllo delle revoche di certificati. La funzione CertVerifyCertificateChainPolicy non verifica se i certificati nella catena di certificati vengono revocati.

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