Função MsiGetFileSignatureInformationA (msi.h)

Artigo
11/20/2024

A função MsiGetFileSignatureInformation usa o caminho para um arquivo que foi assinado digitalmente e retorna o certificado e o hash do signatário do arquivo. msiGetFileSignatureInformation pode ser chamado para obter o certificado do signatário e o hash necessários para preencher o MsiDigitalCertificate, MsiPatchCertificatee tabelas MsiDigitalSignature.

Windows Installer 3.0 e posterior: Começando com o Windows Installer 3.0, o Windows Installer pode verificar as assinaturas digitais de patches (arquivos .msp) usando as tabelas MsiPatchCertificate e MsiDigitalCertificate. Para obter mais informações, consulte Diretrizes para criação de instalações seguras e controle de conta de usuário (UAC).

Windows Installer 2.0: não há suporte para assinaturas digitais de patches . O Windows Installer 2.0 usa assinaturas digitais como um meio de detectar recursos corrompidos e só pode verificar as assinaturas digitais de gabinetes externos e apenas pelo uso das tabelas MsiDigitalSignature e MsiDigitalCertificate.

Sintaxe

HRESULT MsiGetFileSignatureInformationA(
  [in]      LPCSTR         szSignedObjectPath,
  [in]      DWORD          dwFlags,
  [out]     PCCERT_CONTEXT *ppcCertContext,
  [out]     LPBYTE         pbHashData,
  [in, out] LPDWORD        pcbHashData
);

Parâmetros

[in] szSignedObjectPath

Ponteiro para uma cadeia de caracteres terminada em nulo especificando o caminho completo para o arquivo que contém a assinatura digital.

[in] dwFlags

Sinalizadores especiais de caso de erro.

Bandeira	Significado
MSI_INVALID_HASH_IS_FATAL 0x1	Sem esse conjunto de sinalizadores e ao solicitar apenas o contexto do certificado, um hash inválido na assinatura digital não faz com que MsiGetFileSignatureInformation retorne um erro fatal. Para retornar um erro fatal para um hash inválido, defina o sinalizador MSI_INVALID_HASH_IS_FATAL.

[out] ppcCertContext

Contexto de certificado do signatário retornado

[out] pbHashData

Buffer de hash retornado. Esse parâmetro poderá ser NULL se os dados de hash não estiverem sendo solicitados.

[in, out] pcbHashData

Ponteiro para uma variável que especifica o tamanho, em bytes, do buffer apontado pelo parâmetro pbHashData. Esse parâmetro não poderá ser NULL se pbHashData não estiverNULL. Se ERROR_MORE_DATA for retornado, pbHashData fornecerá o tamanho do buffer necessário para armazenar os dados de hash. Se ERROR_SUCCESS for retornado, ele fornecerá o número de bytes gravados no buffer de hash. O parâmetro pcbHashData será ignorado se pbHashData estiver NULL.

Valor de retorno

Valor	Significado
ERROR_SUCCESS/S_OK	Conclusão bem-sucedida.
ERROR_INVALID_PARAMETER	O parâmetro inválido foi especificado.
ERROR_FUNCTION_FAILED	WinVerifyTrust não está disponível no sistema. msiGetFileSignatureInformation requer a presença do arquivo Wintrust.dll no sistema.
ERROR_MORE_DATA	Um buffer é muito pequeno para conter os dados solicitados. Se ERROR_MORE_DATA for retornado, pcbHashData fornecerá o tamanho do buffer necessário para armazenar os dados de hash.
TRUST_E_NOSIGNATURE	O arquivo não está assinado
TRUST_E_BAD_DIGEST	O hash atual do arquivo é inválido de acordo com o hash armazenado na assinatura digital do arquivo.
CERT_E_REVOKED	O certificado do signatário do arquivo foi revogado. A assinatura digital do arquivo está comprometida.
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.
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.

MsiGetFileSignatureInformation também retorna todos os valores de erro Win32 mapeados para seu tipo de dados hresult equivalente HRESULT_FROM_WIN32.

Observações

Ao solicitar apenas o contexto do certificado, um hash inválido na assinatura digital não faz com que MsiGetFileSignatureInformation retorne um erro fatal. Para retornar um erro fatal para um hash inválido, defina o sinalizador MSI_INVALID_HASH_IS_FATAL no parâmetro dwFlags.

As informações de contexto e hash do certificado são extraídas do arquivo por uma chamada para WinVerifyTrust. O parâmetro ppcCertContext é uma duplicata do contexto do certificado do signatário da assinatura. É responsabilidade do chamador chamar CertFreeCertificateContext para liberar o contexto do certificado quando terminar.

Observe que msiGetFileSignatureInformation requer a presença do arquivo Wintrust.dll no sistema.

Nota

O cabeçalho msi.h define MsiGetFileSignatureInformation como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Installer 5.0 no Windows Server 2012, Windows 8, Windows Server 2008 R2 ou Windows 7. Windows Installer 4.0 ou Windows Installer 4.5 no Windows Server 2008 ou Windows Vista. Windows Installer no Windows Server 2003 ou Windows XP. Consulte os Requisitos de Run-Time do Windows Installer para obter informações sobre o service pack mínimo do Windows exigido por uma versão do Windows Installer.
da Plataforma de Destino	Windows
cabeçalho	msi.h
biblioteca	Msi.lib
de DLL	Msi.dll

Consulte também

assinaturas digitais e do Windows Installer

tabela MsiDigitalCertificate

tabela MsiDigitalSignature

Compartilhar via