Função CryptCreateHash (wincrypt.h)
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 |
|---|---|
|
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 |
|---|---|
|
Um dos parâmetros especifica um identificador que não é válido. |
|
Um dos parâmetros contém um valor que não é válido. Geralmente, esse é um ponteiro que não é válido. |
|
O sistema operacional ficou sem memória durante a operação. |
|
O parâmetro Argel especifica um algoritmo ao qual esse CSP não dá suporte. |
|
O parâmetro dwFlags é diferente de zero. |
|
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. |
|
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.
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 |