Funzione WinVerifyTrust (wintrust.h)

  • Articolo

La funzione WinVerifyTrust esegue un'azione di verifica dell'attendibilità su un oggetto specificato. La funzione passa la richiesta a un provider di attendibilità che supporta l'identificatore dell'azione, se presente.

Per la verifica del certificato, usare le funzioni CertGetCertificateChain e CertVerifyCertificateChainPolicy .

Sintassi

LONG WinVerifyTrust(
  [in] HWND   hwnd,
  [in] GUID   *pgActionID,
  [in] LPVOID pWVTData
);

Parametri

[in] hwnd

Handle facoltativo per una finestra del chiamante. Un provider di trust può usare questo valore per determinare se può interagire con l'utente. Tuttavia, i provider di attendibilità eseguono in genere azioni di verifica senza input dell'utente.

Questo parametro può avere uno dei valori seguenti.

Valore Significato
INVALID_HANDLE_VALUE
 Non esiste alcun utente interattivo. Il provider di attendibilità esegue l'azione di verifica senza l'assistenza dell'utente.
Zero
 Il provider di attendibilità può usare il desktop interattivo per visualizzare l'interfaccia utente.
Handle di finestra valido
 Un provider di attendibilità può considerare qualsiasi valore diverso da INVALID_HANDLE_VALUE o zero come handle di finestra valido che può usare per interagire con l'utente.

[in] pgActionID

Puntatore a una struttura GUID che identifica un'azione e il provider di attendibilità che supporta tale azione. Questo valore indica il tipo di azione di verifica da eseguire sulla struttura a cui punta pWinTrustData.

Il servizio WinTrust è progettato per lavorare con provider di attendibilità implementati da terze parti. Ogni provider di trust fornisce un proprio set univoco di identificatori di azione. Per informazioni sugli identificatori di azione supportati da un provider di attendibilità, vedere la documentazione relativa al provider di attendibilità.

Ad esempio, Microsoft fornisce un provider di attendibilità del server di pubblicazione software che può stabilire l'attendibilità del software scaricato da Internet o da un'altra rete pubblica. Il provider di attendibilità del server di pubblicazione software supporta gli identificatori di azione seguenti. Queste costanti sono definite in Softpub.h.

Valore Significato
DRIVER_ACTION_VERIFY
 Verificare l'autenticità di un driver firmato windows Hardware Quality Labs (WHQL). Si tratta di un provider di criteri del componente aggiuntivo Authenticode.
HTTPSPROV_ACTION
 Verificare una connessione SSL/TLS tramite Internet Explorer.
OFFICESIGN_ACTION_VERIFY
 Questo ID azione non è supportato. Verificare l'autenticità di un file di archiviazione strutturato usando il provider di criteri del componente aggiuntivo Microsoft Office Authenticode.

Windows Server 2003 e Windows XP: Questo ID azione è supportato.
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 Verificare le catene di certificati create da qualsiasi tipo di oggetto. Viene fornito un callback per implementare i criteri della catena finale usando il contesto della catena per ogni firmatario e firmatario del contatore.
WINTRUST_ACTION_GENERIC_VERIFY_V2
 Verificare un file o un oggetto usando il provider di criteri Authenticode.
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 Scrivere la struttura CRYPT_PROVIDER_DATA in un file dopo aver chiamato il provider di criteri Authenticode.

[in] pWVTData

Puntatore che, quando viene eseguito il cast come struttura di WINTRUST_DATA , contiene informazioni necessarie al provider di attendibilità per elaborare l'identificatore di azione specificato. In genere, la struttura include informazioni che identificano l'oggetto che il provider di attendibilità deve valutare.

Il formato della struttura dipende dall'identificatore dell'azione. Per informazioni sui dati necessari per un identificatore di azione specifico, vedere la documentazione relativa al provider di attendibilità che supporta tale azione.

Valore restituito

Se il provider di attendibilità verifica che l'oggetto sia considerato attendibile per l'azione specificata, il valore restituito è zero. Nessun altro valore oltre a zero deve essere considerato un risultato positivo.

Se il provider di attendibilità non verifica che l'oggetto sia considerato attendibile per l'azione specificata, la funzione restituisce un codice di stato dal provider di attendibilità.

Nota Il valore restituito è long, non HRESULT come documentato in precedenza. Non utilizzare macro HRESULT , ad esempio SUCCEEDED , per determinare se la funzione ha avuto esito positivo. Controllare invece che il valore restituito sia uguale a zero.

 

Ad esempio, un provider di attendibilità potrebbe indicare che l'oggetto non è attendibile o è attendibile, ma con limitazioni o avvisi. Il valore restituito può essere un valore specifico del provider di attendibilità descritto nella documentazione per un singolo provider di attendibilità oppure può essere uno dei codici di errore seguenti.

Codice restituito Descrizione
TRUST_E_SUBJECT_NOT_TRUSTED
 L'oggetto non ha superato l'azione di verifica specificata. La maggior parte dei provider di attendibilità restituisce un codice di errore più dettagliato che descrive il motivo dell'errore.
Nota  

Il codice restituito TRUST_E_SUBJECT_NOT_TRUSTED può essere restituito a seconda del valore della chiave del Registro di sistema EnableCertPaddingCheck in HKLM\Software\Microsoft\Cryptography\Wintrust\Config. Se EnableCertPaddingCheck è impostato su "1", viene eseguito un controllo aggiuntivo per verificare che la struttura WIN_CERTIFICATE non contenga informazioni estranee. Il controllo verifica che non siano presenti dati diversi da zero oltre la struttura PKCS #7. Per altre informazioni, vedere l'avviso di sicurezza seguente: http://technet.microsoft.com/security/advisory/2915720#section1.

 
TRUST_E_PROVIDER_UNKNOWN
 Il provider di attendibilità non viene riconosciuto in questo sistema.
TRUST_E_ACTION_UNKNOWN
 Il provider di attendibilità non supporta l'azione specificata.
TRUST_E_SUBJECT_FORM_UNKNOWN
 Il provider di attendibilità non supporta il modulo specificato per l'oggetto.

Commenti

La funzione WinVerifyTrust consente alle applicazioni di richiamare un provider di attendibilità per verificare che un oggetto specificato soddisfi i criteri di un'operazione di verifica specificata. Il parametro pgActionID identifica l'operazione di verifica e il parametro pWinTrustData identifica l'oggetto il cui trust deve essere verificato. Un provider di attendibilità è una DLL registrata con il sistema operativo. Una chiamata a WinVerifyTrust inoltra la chiamata al provider di attendibilità registrato, se presente, che supporta tale identificatore di azione specificato.

Ad esempio, il provider di attendibilità autore software può verificare che un file di immagine eseguibile provenga da un autore di software attendibile e che il file non sia stato modificato dopo la pubblicazione. In questo caso, il parametro pWinTrustData specifica il nome del file e il tipo di file, ad esempio un file di immagine eseguibile portabile Microsoft.

Ogni provider di attendibilità supporta un set specifico di azioni che può valutare. Ogni azione ha un GUID che lo identifica. Un provider di attendibilità può supportare un numero qualsiasi di identificatori di azione, ma due provider di attendibilità non possono supportare lo stesso identificatore di azione.

Per un esempio che illustra come usare questa funzione per verificare la firma di un file eseguibile portabile (PE), vedere Esempio di programma C: Verifica della firma di un file PE.

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione wintrust.h (include Softpub.h)
Libreria Wintrust.lib
DLL Wintrust.dll