Função BCryptCreateHash (bcrypt.h)

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

Sintaxe

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

Parâmetros

[in, out] hAlgorithm

O identificador de um provedor de algoritmo que dá suporte à interface hash ou MAC. Esse identificador é obtido chamando a função BCryptOpenAlgorithmProvider ou pode ser um pseudo-identificador do algoritmo CNG.

[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 de hash ou MAC subsequentes, como a função BCryptHashData . Quando terminar de usar esse identificador, libere-o passando-o para a função BCryptDestroyHash .

[out, optional] 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 do identificador de algoritmo. 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 por essa função e liberada por BCryptDestroyHash. Windows 7: Essa funcionalidade de gerenciamento de memória está disponível a partir do Windows 7.

[in] 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 por essa função e liberada por BCryptDestroyHash. 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 um MAC. O parâmetro cbSecret contém o tamanho desse buffer. Se usado com um algoritmo de hash, o algoritmo deve ter sido promovido ao HMAC usando o sinalizador BCRYPT_ALG_HANDLE_HMAC no BCryptOpenAlgorithmProvider.

Para calcular um hash, defina esse parâmetro como NULL.

[in] cbSecret

O tamanho, em bytes, do buffer 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 seguinte valor:

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.

Observações

Ao usar um provedor de algoritmo com suporte, BCryptCreateHash pode ser chamado do modo de usuário ou do modo kernel. Os chamadores do modo kernel podem executar 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 BCRYPT_PROV_DISPATCH e todos os ponteiros passados para a função BCryptCreateHash deverão se referir à memória não paga (ou bloqueada).

O chamador deve liberar phHash com BCryptDestroyHash quando o objeto não estiver mais em uso.

Para chamar essa função no modo kernel, use Cng.lib, que faz parte do DDK (Driver Development Kit). Windows Server 2008 e Windows Vista: Para chamar essa função no modo kernel, use Ksecdd.lib.

Requisitos

Consulte também

BCryptDuplicateHash

BCryptHashData

BCryptFinishHash

BCryptDestroyHash