Função CryptGetHashParam (wincrypt.h)

Artigo
08/27/2023

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 CryptGetHashParam recupera dados que regem as operações de um objeto hash. O valor de hash real pode ser recuperado usando essa função.

Sintaxe

BOOL CryptGetHashParam(
  [in]      HCRYPTHASH hHash,
  [in]      DWORD      dwParam,
  [out]     BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwFlags
);

Parâmetros

[in] hHash

Identificador do objeto hash a ser consultado.

[in] dwParam

Tipo de consulta. Esse parâmetro pode ser definido como uma das consultas a seguir.

Valor	Significado
HP_ALGID Algoritmo de hash	Um ALG_ID que indica o algoritmo especificado quando o objeto hash foi criado. Para obter uma lista de algoritmos de hash, consulte CryptCreateHash.
HP_HASHSIZE Tamanho do valor de hash	Valor DWORD que indica o número de bytes no valor de hash. Esse valor variará dependendo do algoritmo de hash. Os aplicativos devem recuperar esse valor pouco antes do valor HP_HASHVAL para que a quantidade correta de memória possa ser alocada.
HP_HASHVAL Valor de hash	O valor de hash ou hash de mensagem para o objeto hash especificado por hHash. Esse valor é gerado com base nos dados fornecidos ao objeto hash anteriormente por meio das funções CryptHashData e CryptHashSessionKey . A função CryptGetHashParam conclui o hash. Depois que CryptGetHashParam tiver sido chamado, não será possível adicionar mais dados ao hash. As chamadas adicionais para CryptHashData ou CryptHashSessionKey falham. Depois que o aplicativo for concluído com o hash, CryptDestroyHash deverá ser chamado para destruir o objeto hash.

Nota Os CSPs podem adicionar mais valores que essa função pode consultar.

[out] pbData

Um ponteiro para um buffer que recebe os dados de valor especificados. A forma desses dados varia, dependendo do número do valor.

Esse parâmetro pode ser NULL para determinar o tamanho da memória necessário.

[in, out] pdwDataLen

Um ponteiro para um valor DWORD que especifica o tamanho, em bytes, do buffer pbData . Quando a função retorna, o valor DWORD contém o número de bytes armazenados no buffer.

Se pbData for NULL, defina o valor de pdwDataLen como zero.

Nota Ao processar os dados retornados no buffer, os aplicativos devem usar o tamanho real dos dados retornados. O tamanho real pode ser ligeiramente menor do que o tamanho do buffer especificado na entrada. (Na entrada, os tamanhos de buffer geralmente são especificados grandes o suficiente para garantir que os maiores dados de saída possíveis caibam no buffer.) Na saída, a variável apontada por esse parâmetro é atualizada para refletir o tamanho real dos dados copiados para o buffer.

[in] dwFlags

Reservado para uso futuro e deve ser zero.

Valor retornado

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. Geralmente, esse é um ponteiro que não é válido.
ERROR_MORE_DATA	Se o buffer especificado pelo parâmetro pbData não for grande o suficiente para manter os dados retornados, a função definirá o código ERROR_MORE_DATA e armazenará o tamanho do buffer necessário, em bytes, na variável apontada por pdwDataLen.
NTE_BAD_FLAGS	O parâmetro dwFlags é diferente de zero.
NTE_BAD_HASH	O objeto hash especificado pelo parâmetro hHash não é válido.
NTE_BAD_TYPE	O parâmetro dwParam especifica um número de valor desconhecido.
NTE_BAD_UID	O contexto CSP especificado quando o hash foi criado não pode ser encontrado.

Requisitos


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