Função WinVerifyTrust (wintrust.h)

  • Artigo

A função WinVerifyTrust executa uma ação de verificação de confiança em um objeto especificado. A função passa a consulta para um provedor de confiança que dá suporte ao identificador de ação, se houver.

Para verificação de certificado, use as funções CertGetCertificateChain e CertVerifyCertificateChainPolicy .

Sintaxe

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

Parâmetros

[in] hwnd

Identificador opcional para uma janela do chamador. Um provedor de confiança pode usar esse valor para determinar se ele pode interagir com o usuário. No entanto, os provedores de confiança normalmente executam ações de verificação sem a entrada do usuário.

Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
INVALID_HANDLE_VALUE
 Não há nenhum usuário interativo. O provedor de confiança executa a ação de verificação sem a assistência do usuário.
Zero
 O provedor de confiança pode usar a área de trabalho interativa para exibir sua interface do usuário.
Um identificador de janela válido
 Um provedor de confiança pode tratar qualquer valor diferente de INVALID_HANDLE_VALUE ou zero como um identificador de janela válido que ele pode usar para interagir com o usuário.

[in] pgActionID

Um ponteiro para uma estrutura GUID que identifica uma ação e o provedor de confiança que dá suporte a essa ação. Esse valor indica o tipo de ação de verificação a ser executada na estrutura apontada por pWinTrustData.

O serviço WinTrust foi projetado para trabalhar com provedores de confiança implementados por terceiros. Cada provedor de confiança fornece seu próprio conjunto exclusivo de identificadores de ação. Para obter informações sobre os identificadores de ação com suporte de um provedor de confiança, consulte a documentação desse provedor de confiança.

Por exemplo, a Microsoft fornece um Provedor de Confiança do Editor de Software que pode estabelecer a confiabilidade do software que está sendo baixado da Internet ou de alguma outra rede pública. O Provedor de Confiança do Editor de Software dá suporte aos seguintes identificadores de ação. Essas constantes são definidas em Softpub.h.

Valor Significado
DRIVER_ACTION_VERIFY
 Verifique a autenticidade de um driver assinado do WHQL (Hardware Quality Labs) do Windows. Este é um provedor de política de complemento authenticode.
HTTPSPROV_ACTION
 Verifique uma conexão SSL/TLS por meio de Explorer da Internet.
OFFICESIGN_ACTION_VERIFY
 Não há suporte para essa ID de Ação. Verifique a autenticidade de um arquivo de armazenamento estruturado usando o provedor de política de complemento Microsoft Office Authenticode.

Windows Server 2003 e Windows XP: Há suporte para essa ID de Ação.
WINTRUST_ACTION_GENERIC_CHAIN_VERIFY
 Verifique as cadeias de certificados criadas a partir de qualquer tipo de objeto. Um retorno de chamada é fornecido para implementar a política de cadeia final usando o contexto de cadeia para cada signatário e signatário de contador.
WINTRUST_ACTION_GENERIC_VERIFY_V2
 Verifique um arquivo ou objeto usando o provedor de política Authenticode.
WINTRUST_ACTION_TRUSTPROVIDER_TEST
 Escreva a estrutura CRYPT_PROVIDER_DATA em um arquivo depois de chamar o provedor de política Authenticode.

[in] pWVTData

Um ponteiro que, quando convertido como uma estrutura WINTRUST_DATA , contém informações de que o provedor de confiança precisa para processar o identificador de ação especificado. Normalmente, a estrutura inclui informações que identificam o objeto que o provedor de confiança deve avaliar.

O formato da estrutura depende do identificador de ação. Para obter informações sobre os dados necessários para um identificador de ação específico, consulte a documentação do provedor de confiança que dá suporte a essa ação.

Retornar valor

Se o provedor de confiança verificar se o assunto é confiável para a ação especificada, o valor retornado será zero. Nenhum outro valor além de zero deve ser considerado um retorno bem-sucedido.

Se o provedor de confiança não verificar se o assunto é confiável para a ação especificada, a função retornará um código status do provedor de confiança.

Nota O valor retornado é LONG, não um HRESULT , conforme documentado anteriormente. Não use macros HRESULT como SUCCEEDED para determinar se a função foi bem-sucedida. Em vez disso, marcar o valor retornado para igualdade como zero.

 

Por exemplo, um provedor de confiança pode indicar que o assunto não é confiável ou é confiável, mas com limitações ou avisos. O valor retornado pode ser um valor específico do provedor de confiança descrito na documentação de um provedor de confiança individual ou pode ser um dos seguintes códigos de erro.

Código de retorno Descrição
TRUST_E_SUBJECT_NOT_TRUSTED
 O assunto falhou na ação de verificação especificada. A maioria dos provedores de confiança retorna um código de erro mais detalhado que descreve o motivo da falha.
Observação  

O código de retorno TRUST_E_SUBJECT_NOT_TRUSTED pode ser retornado dependendo do valor da chave do Registro EnableCertPaddingCheck em HKLM\Software\Microsoft\Cryptography\Wintrust\Config. Se EnableCertPaddingCheck estiver definido como "1", um marcar adicional será executado para verificar se a estrutura WIN_CERTIFICATE não contém informações desnecessárias. O marcar valida que não há dados diferentes de zero além da estrutura PKCS nº 7. Para obter mais informações, consulte a seguinte consultoria de segurança: http://technet.microsoft.com/security/advisory/2915720#section1.

 
TRUST_E_PROVIDER_UNKNOWN
 O provedor de confiança não é reconhecido nesse sistema.
TRUST_E_ACTION_UNKNOWN
 O provedor de confiança não dá suporte à ação especificada.
TRUST_E_SUBJECT_FORM_UNKNOWN
 O provedor de confiança não dá suporte ao formulário especificado para o assunto.

Comentários

A função WinVerifyTrust permite que os aplicativos invoquem um provedor de confiança para verificar se um objeto especificado atende aos critérios de uma operação de verificação especificada. O parâmetro pgActionID identifica a operação de verificação e o parâmetro pWinTrustData identifica o objeto cuja confiança deve ser verificada. Um provedor de confiança é uma DLL registrada no sistema operacional. Uma chamada para WinVerifyTrust encaminha essa chamada para o provedor de confiança registrado, se houver uma, que dá suporte ao identificador de ação especificado.

Por exemplo, o Provedor de Confiança do Editor de Software pode verificar se um arquivo de imagem executável vem de um editor de software confiável e se o arquivo não foi modificado desde que foi publicado. Nesse caso, o parâmetro pWinTrustData especifica o nome do arquivo e o tipo de arquivo, como um arquivo de imagem executável portátil da Microsoft.

Cada provedor de confiança dá suporte a um conjunto específico de ações que ele pode avaliar. Cada ação tem um GUID que a identifica. Um provedor de confiança pode dar suporte a qualquer número de identificadores de ação, mas dois provedores de confiança não podem dar suporte ao mesmo identificador de ação.

Para obter um exemplo que demonstra como usar essa função para verificar a assinatura de um arquivo PE (executável portátil), consulte Exemplo de programa C: verificando a assinatura de um arquivo PE.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows XP [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2003 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho wintrust.h (inclua Softpub.h)
Biblioteca Wintrust.lib
DLL Wintrust.dll