Função CryptCreateHash (wincrypt.h)

Artigo
03/03/2024

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

A função CryptCreateHash inicia o hash de um fluxo de dados. Ele cria e retorna ao aplicativo de chamada um identificador para um objeto de hash do CSP (provedor de serviços criptográficos). Esse identificador é usado em chamadas subsequentes para CryptHashData e CryptHashSessionKey para chaves de sessão de hash e outros fluxos de dados.

Sintaxe

BOOL CryptCreateHash(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  HCRYPTKEY  hKey,
  [in]  DWORD      dwFlags,
  [out] HCRYPTHASH *phHash
);

Parâmetros

[in] hProv

Um identificador para um CSP criado por uma chamada para CryptAcquireContext.

[in] Algid

Um valor ALG_ID que identifica o algoritmo de hash a ser usado.

Os valores válidos para esse parâmetro variam, dependendo do CSP usado. Para obter uma lista de algoritmos padrão, consulte Comentários.

[in] hKey

Se o tipo de algoritmo de hash for um hash com chave, como o algoritmo HMAC ( Código de Autenticação de Mensagem Baseado em Hash ) ou MAC ( Código de Autenticação de Mensagem ), a chave para o hash será passada nesse parâmetro. Para algoritmos não chaveados, esse parâmetro deve ser definido como zero.

Para algoritmos com chave, a chave deve ser para uma chave de criptografia de bloco , como RC2, que tem um modo de criptografia de CBC ( Encadeamento de Blocos de Criptografia ).

[in] dwFlags

O valor do sinalizador a seguir é definido.

Valor	Significado
CRYPT_SECRETDIGEST 0x00000001	Esse sinalizador não é usado.

[out] phHash

O endereço para o qual a função copia um identificador para o novo objeto hash. Quando terminar de usar o objeto hash, solte o identificador chamando a função CryptDestroyHash .

Retornar valor

Se a função for bem-sucedida, a função retornará TRUE.

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

Os códigos de erro precedidos pelo NTE são gerados pelo CSP específico que você está usando. A tabela a seguir mostra alguns dos códigos de erro possíveis.

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. Geralmente, esse é um ponteiro que não é válido.
ERROR_NOT_ENOUGH_MEMORY	O sistema operacional ficou sem memória durante a operação.
NTE_BAD_ALGID	O parâmetro Argel especifica um algoritmo ao qual esse CSP não dá suporte.
NTE_BAD_FLAGS	O parâmetro dwFlags é diferente de zero.
NTE_BAD_KEY	Um algoritmo de hash com chave, como CALG_MAC, é especificado por Algid e o parâmetro hKey é zero ou especifica um identificador de chave que não é válido. Esse código de erro também será retornado se a chave for para uma codificação de fluxo ou se o modo de criptografia for algo diferente de CBC.
NTE_NO_MEMORY	O CSP ficou sem memória durante a operação.

Comentários

Para obter uma lista de provedores de serviços da Microsoft e os algoritmos que eles implementam, consulte Provedores de Serviços Criptográficos da Microsoft.

A computação do hash real é feita com as funções CryptHashData e CryptHashSessionKey . Eles exigem um identificador para o objeto hash. Depois que todos os dados tiverem sido adicionados ao objeto hash, qualquer uma das seguintes operações poderá ser executada:

O valor de hash pode ser recuperado usando CryptGetHashParam.
Uma chave de sessão pode ser derivada usando CryptDeriveKey.
O hash pode ser assinado usando CryptSignHash.
Uma assinatura pode ser verificada usando CryptVerifySignature.

Depois que uma das funções dessa lista tiver sido chamada, CryptHashData e CryptHashSessionKey não poderão ser chamados .

Exemplos

O exemplo a seguir mostra como iniciar o hash de um fluxo de dados. Ele cria e retorna ao aplicativo de chamada um identificador para um objeto hash. Esse identificador é usado em chamadas subsequentes para CryptHashData e CryptHashSessionKey para fazer hash de qualquer fluxo de dados. Para obter um exemplo que inclui o contexto completo para este exemplo, consulte Exemplo de programa C: criando e hash de uma chave de sessão. Para obter outro exemplo que usa essa função, consulte Exemplo de programa C: assinando um hash e Verificando a assinatura de hash.

//--------------------------------------------------------------------
//  Declare variables.

HCRYPTPROV hCryptProv;
HCRYPTHASH hHash;

//--------------------------------------------------------------------
// Get a handle to a cryptography provider context.


if(CryptAcquireContext(
   &hCryptProv, 
   NULL, 
   NULL, 
   PROV_RSA_FULL, 
   0)) 
{
    printf("CryptAcquireContext complete. \n");
}
else
{
     printf("Acquisition of context failed.\n");
     exit(1);
}
//--------------------------------------------------------------------
// Acquire a hash object handle.

if(CryptCreateHash(
   hCryptProv, 
   CALG_MD5, 
   0, 
   0, 
   &hHash)) 
{
    printf("An empty hash object has been created. \n");
}
else
{
    printf("Error during CryptBeginHash!\n");
    exit(1);
}

// Insert code that uses the hash object here.

//--------------------------------------------------------------------
// After processing, hCryptProv and hHash must be released.

if(hHash) 
   CryptDestroyHash(hHash);
if(hCryptProv) 
   CryptReleaseContext(hCryptProv,0);

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