Função BCryptCreateMultiHash (bcrypt.h)

Artigo
02/23/2024

A função BCryptCreateMultiHash cria um estado de vários hash que permite a computação paralela de várias operações de hash. Esse estado de vários hash é usado pela função BCryptProcessMultiOperations . O estado de vários hash pode ser considerado como uma matriz de objetos hash, cada um deles equivalente a um criado por BCryptCreateHash.

Os cálculos paralelos podem aumentar consideravelmente a taxa de transferência geral, em detrimento do aumento da latência para cálculos individuais.

No momento, os cálculos de hash paralelo são implementados apenas para SHA-256, SHA-384 e SHA-512. Outros algoritmos de hash podem ser usados com a API de computação paralela, mas são executados na taxa de transferência das operações de hash sequencial. O conjunto de algoritmos de hash que podem se beneficiar de cálculos paralelos pode mudar em atualizações futuras.

Sintaxe

NTSTATUS BCryptCreateMultiHash(
  BCRYPT_ALG_HANDLE  hAlgorithm,
  BCRYPT_HASH_HANDLE *phHash,
  ULONG              nHashes,
  PUCHAR             pbHashObject,
  ULONG              cbHashObject,
  PUCHAR             pbSecret,
  ULONG              cbSecret,
  ULONG              dwFlags
);

Parâmetros

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

O identificador de algoritmo usado para todos os estados de hash na matriz de vários hash. O identificador de algoritmo deve ter sido aberto com o BCYRPT_MULTI_FLAG passado para a função BCryptOpenAlgorithmProvider . Como alternativa, o chamador pode usar os pseudo-identificadores.

phHash

BCRYPT_HASH_HANDLE* [out]

Um ponteiro para um valor BCRYPT_HASH_HANDLE que recebe um identificador que representa o estado de vários hash. Esse identificador é usado em operações subsequentes, como BCryptProcessMultiOperations. Quando terminar de usar esse identificador, solte-o passando-o para a função BCryptDestroyHash .

nHashes

ULONG[in]

O número de elementos na matriz. O estado de vários hash que essa função cria é capaz de executar cálculos paralelos em nHashes diferentes estados de hash.

pbHashObject

PUCHAR[out]

Um ponteiro para um buffer que recebe o estado de vários hash.

O tamanho pode ser calculado com base nos membros cbPerObject e cbPerElement da estrutura BCRYPT_MULTI_OBJECT_LENGTH_STRUCT . O valor é o seguinte: cbPerObject + (number of hash states) * cbPerElement.

Se pbHashObject for NULL e cbHashObject tiver um valor zero (0), o buffer de objeto será alocado automaticamente.

cbHashObject

ULONG[in]

O tamanho do buffer pbHashObject ou zero (0) se pbHashObject for NULL.

pbSecret

PUCHAR[in]

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 . Caso contrário, defina esse parâmetro como NULL.

A mesma chave é usada para todos os elementos da matriz.

cbSecret

ULONG[in]

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

dwFlags

ULONG[in]

Sinalizadores que modificam o comportamento da função. Isso pode ser zero ou os valores abaixo. Objetos de vários hash são sempre reutilizáveis e sempre se comportam como se o BCRYPT_HASH_REUSABLE_FLAG fosse passado. Esse sinalizador tem suporte aqui para consistência.

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 com CNG.

Retornar valor

Retorna um código status que indica o êxito ou a falha da função. Se o método for bem-sucedido, ele retornará STATUS_SUCCESS. Para outros valores NTSTATUS , consulte Valores NTSTATUS.

Comentários

Internamente, as computações de hash paralelas são feitas usando instruções SIMD (vários dados de instrução única) com até 8 cálculos paralelos por vez, dependendo do algoritmo de hash e dos recursos de CPU disponíveis. Para maximizar o desempenho, recomendamos que o chamador forneça pelo menos oito computações que podem ser processadas em paralelo.

Para cálculos de comprimento desigual, fornecer mais cálculos em paralelo permite que a implementação agende melhor os cálculos entre os registros de CPU. Isso pode fornecer um benefício de taxa de transferência. Para obter a taxa de transferência ideal, recomendamos que o chamador forneça entre oito e 100 computações. Selecione um valor mais baixo nesse intervalo somente se todos os cálculos de hash tiverem o mesmo comprimento.

Não há suporte para vários hashs para HMAC-MD2, HMAC-MD4 e GMAC.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 8.1 Update [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Atualização do Windows Server 2008 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	bcrypt.h
Biblioteca	Bcrypt.lib
DLL	Bcrypt.dll