Função CryptVerifySignatureA (wincrypt.h)

Artigo
08/27/2023

Importante Essa API foi preterida. O software novo e existente deve começar a usar APIs de Criptografia de Próxima Geração. A Microsoft pode remover essa API em versões futuras.

A função CryptVerifySignature verifica a assinatura de um objeto hash.

Antes de chamar essa função, CryptCreateHash deve ser chamado para criar o identificador de um objeto hash. CryptHashData ou CryptHashSessionKey é usado para adicionar dados ou chaves de sessão ao objeto hash.

Depois que CryptVerifySignature for concluído, somente CryptDestroyHash poderá ser chamado usando o identificador hHash .

Sintaxe

BOOL CryptVerifySignatureA(
  [in] HCRYPTHASH hHash,
  [in] const BYTE *pbSignature,
  [in] DWORD      dwSigLen,
  [in] HCRYPTKEY  hPubKey,
  [in] LPCSTR     szDescription,
  [in] DWORD      dwFlags
);

Parâmetros

[in] hHash

Um identificador para o objeto hash a ser verificado.

[in] pbSignature

O endereço dos dados de assinatura a serem verificados.

[in] dwSigLen

O número de bytes nos dados de assinatura pbSignature .

[in] hPubKey

Um identificador para a chave pública a ser usada para autenticar a assinatura. Essa chave pública deve pertencer ao par de chaves que foi originalmente usado para criar a assinatura digital.

[in] szDescription

Esse parâmetro não deve mais ser usado e deve ser definido como NULL para evitar vulnerabilidades de segurança. No entanto, ainda há suporte para compatibilidade com versões anteriores no Provedor Criptográfico base da Microsoft.

[in] dwFlags

Os valores de sinalizador a seguir são definidos.

Valor	Significado
CRYPT_NOHASHOID 0x00000001	Esse sinalizador é usado com provedores RSA. Ao verificar a assinatura, não se espera que o OID ( identificador de objeto hash) esteja presente ou verificado. Se esse sinalizador não estiver definido, o OID de hash na assinatura padrão será verificado conforme especificado na definição de DigestInfo no PKCS nº 7.
CRYPT_TYPE2_FORMAT 0x00000002	Esse sinalizador não é usado.
CRYPT_X931_FORMAT 0x00000004	Use o suporte do X.931 para a versão compatível com FIPS 186-2 do RSA (rDSA).

Retornar valor

Se a função for bem-sucedida, o valor retornado será TRUE.

Se a função falhar, o valor retornado será FALSE. Para obter informações de erro estendidas, chame GetLastError.

Os códigos de erro precedidos por "NTE" são gerados pelo CSP específico que você está usando. Alguns códigos de erro possíveis seguem.

Código de retorno	Descrição
ERROR_INVALID_HANDLE	Um dos parâmetros especifica um identificador que não é válido.
ERROR_INVALID_PARAMETER	Um dos parâmetros contém um valor que não é válido. Isso geralmente é um ponteiro que não é válido.
NTE_BAD_FLAGS	O parâmetro dwFlags não é zero.
NTE_BAD_HASH	O objeto hash especificado pelo parâmetro hHash não é válido.
NTE_BAD_KEY	O parâmetro hPubKey não contém um identificador para uma chave pública válida.
NTE_BAD_SIGNATURE	A assinatura não era válida. Isso pode ocorrer porque os dados em si foram alterados, a cadeia de caracteres de descrição não correspondeu ou a chave pública errada foi especificada por hPubKey. Esse erro também poderá ser retornado se os algoritmos de hash ou assinatura não corresponderem aos usados para criar a assinatura.
NTE_BAD_UID	O contexto do CSP ( provedor de serviços criptográficos ) especificado quando o objeto hash foi criado não foi encontrado.
NTE_NO_MEMORY	O CSP ficou sem memória durante a operação.

Comentários

A função CryptVerifySignature conclui o hash. Após essa chamada, não é possível adicionar mais dados ao hash. Chamadas adicionais para CryptHashData ou CryptHashSessionKey falham. Depois que o aplicativo for feito com o hash, CryptDestroyHash deverá ser chamado para destruir o objeto hash.

Se você gerar uma assinatura usando as APIs .NET Framework e tentar verificá-la usando a função CryptVerifySignature, a função falhará e GetLastError retornará NTE_BAD_SIGNATURE. Isso ocorre devido aos diferentes pedidos de bytes entre a API nativa do Win32 e a API .NET Framework.

A API de criptografia nativa usa a ordem de byte little-endian, enquanto a API de .NET Framework usa a ordem de bytes big-endian. Se você estiver verificando uma assinatura gerada usando uma API .NET Framework, deverá trocar a ordem dos bytes de assinatura antes de chamar a função CryptVerifySignature para verificar a assinatura.

Exemplos

Para obter um exemplo que usa a função CryptVerifySignature , consulte Exemplo de Programa C: Assinando um hash e Verificando a assinatura de hash.

Observação

O cabeçalho wincrypt.h define CryptVerifySignature como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

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	wincrypt.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll