Função BCryptCreateHash (bcrypt.h)

Artigo
07/16/2024

A função BCryptCreateHash é chamada para criar um objeto mac ( de código de autenticação de mensagem) de ou hash.

Sintaxe

NTSTATUS BCryptCreateHash(
  [in, out]      BCRYPT_ALG_HANDLE  hAlgorithm,
  [out]          BCRYPT_HASH_HANDLE *phHash,
  [out]          PUCHAR             pbHashObject,
  [in, optional] ULONG              cbHashObject,
  [in, optional] PUCHAR             pbSecret,
  [in]           ULONG              cbSecret,
  [in]           ULONG              dwFlags
);

Parâmetros

[in, out] hAlgorithm

O identificador de um provedor de algoritmos criado usando a função BCryptOpenAlgorithmProvider. O algoritmo especificado quando o provedor foi criado deve dar suporte à interface de hash.

[out] phHash

Um ponteiro para um valor BCRYPT_HASH_HANDLE que recebe um identificador que representa o objeto hash ou MAC. Esse identificador é usado em funções mac ou hash subsequentes, como a função BCryptHashData. Quando terminar de usar esse identificador, libere-o passando-o para a função BCryptDestroyHash .

[out] pbHashObject

Um ponteiro para um buffer que recebe o hash ou o objeto MAC. O parâmetro cbHashObject contém o tamanho desse buffer. O tamanho necessário desse buffer pode ser obtido chamando a função BCryptGetProperty para obter a propriedade BCRYPT_OBJECT_LENGTH. Isso fornecerá o tamanho do objeto hash ou MAC para o algoritmo especificado.

Essa memória só pode ser liberada depois que o identificador apontado pelo parâmetro phHash for destruído.

Se o valor desse parâmetro for NULL e o valor do parâmetro cbHashObject for zero, a memória do objeto hash será alocada e liberada por essa função. Windows 7: Essa funcionalidade de gerenciamento de memória está disponível a partir do Windows 7.

[in, optional] cbHashObject

O tamanho, em bytes, do buffer pbHashObject .

Se o valor desse parâmetro for zero e o valor do parâmetro pbHashObject for NULL, a memória do objeto de chave será alocada e liberada por essa função. Windows 7: Essa funcionalidade de gerenciamento de memória está disponível a partir do Windows 7.

[in, optional] pbSecret

Um ponteiro para um buffer que contém a chave a ser usada para o hash ou MAC. O parâmetro cbSecret contém o tamanho desse buffer. Essa chave só se aplica a algoritmos de hash abertos pela função BCryptOpenAlgorithmProvider usando o sinalizador BCRYPT_ALG_HANDLE_HMAC_FLAG . Caso contrário, defina esse parâmetro para NULL.

[in] cbSecret

O tamanho, em bytes, do buffer de pbSecret. Se nenhuma chave for usada, defina esse parâmetro como zero.

[in] dwFlags

Sinalizadores que modificam o comportamento da função. Isso pode ser zero ou o valor a seguir.

Valor	Significado
BCRYPT_HASH_REUSABLE_FLAG	Cria um objeto de hash reutilizável. O objeto pode ser usado para uma nova operação de hash imediatamente após chamar BCryptFinishHash. Para obter mais informações, consulte Criando um hash comCNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 e Windows Vista: Esse sinalizador não tem suporte.

Valor de retorno

Retorna um código de status que indica o êxito ou a falha da função.

Os códigos de retorno possíveis incluem, mas não se limitam a, o seguinte.

Código de retorno	Descrição
STATUS_SUCCESS	A função foi bem-sucedida.
STATUS_BUFFER_TOO_SMALL	O tamanho do objeto hash especificado pelo parâmetro cbHashObject não é grande o suficiente para manter o objeto hash.
STATUS_INVALID_HANDLE	O identificador de algoritmo no parâmetro hAlgorithm não é válido.
STATUS_INVALID_PARAMETER	Um ou mais parâmetros não são válidos.
STATUS_NOT_SUPPORTED	O provedor de algoritmo especificado pelo parâmetro hAlgorithm não dá suporte à interface de hash.

Observações

Dependendo de quais modos de processador um provedor dá suporte, BCryptCreateHash pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem ser executados em PASSIVE_LEVELIRQL ou DISPATCH_LEVEL IRQL. Se o nível IRQL atual for DISPATCH_LEVEL, o identificador fornecido no parâmetro hAlgorithm deverá ter sido aberto usando o sinalizador de BCRYPT_PROV_DISPATCH e todos os ponteiros passados para a função BCryptCreateHash devem se referir à memória nãopagada (ou bloqueada).

Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Para obter mais informações, consulte WDK e ferramentas de desenvolvedor.Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	bcrypt.h
biblioteca	Bcrypt.lib
de DLL	Bcrypt.dll

Consulte também

BCryptDestroyHash

Compartilhar via