Función BCryptCreateMultiHash (bcrypt.h)

Artículo
03/23/2023

La función BCryptCreateMultiHash crea un estado de varios hash que permite el cálculo paralelo de varias operaciones hash. Esta función BCryptProcessMultiOperations usa este estado de varios hashes. El estado de varios hash se puede considerar como una matriz de objetos hash, cada uno de los cuales es equivalente a uno creado por BCryptCreateHash.

Los cálculos paralelos pueden aumentar considerablemente el rendimiento general, a costa de una mayor latencia para cálculos individuales.

Actualmente, los cálculos hash paralelos solo se implementan para SHA-256, SHA-384 y SHA-512. Otros algoritmos hash se pueden usar con la API de cálculo paralelo, pero se ejecutan en el rendimiento de las operaciones hash secuenciales. El conjunto de algoritmos hash que pueden beneficiarse de cálculos paralelos puede cambiar en futuras actualizaciones.

Sintaxis

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]

Identificador de algoritmo usado para todos los estados hash de la matriz de varios hash. El identificador de algoritmo debe haberse abierto con el BCYRPT_MULTI_FLAG pasado a la función BCryptOpenAlgorithmProvider . Como alternativa, el autor de la llamada puede usar los pseudo-identificadores.

phHash

BCRYPT_HASH_HANDLE* [out]

Puntero a un valor de BCRYPT_HASH_HANDLE que recibe un identificador que representa el estado de varios hash. Este identificador se usa en operaciones posteriores, como BCryptProcessMultiOperations. Cuando haya terminado de usar este identificador, suéltelo pasando a la función BCryptDestroyHash .

nHashes

ULONG[in]

Número de elementos de la matriz. El estado de varios hash que crea esta función es capaz de realizar cálculos paralelos en nHashes diferentes estados hash.

pbHashObject

PUCHAR[out]

Puntero a un búfer que recibe el estado de varios hash.

El tamaño se puede calcular a partir de los miembros cbPerObject y cbPerElement de la estructura BCRYPT_MULTI_OBJECT_LENGTH_STRUCT . El valor es el siguiente: cbPerObject + (number of hash states) * cbPerElement.

Si pbHashObject es NULL y cbHashObject tiene un valor de cero (0), el búfer de objetos se asigna automáticamente.

cbHashObject

ULONG[in]

Tamaño del búfer pbHashObject o cero (0) si pbHashObject es NULL.

pbSecret

PUCHAR[in]

Puntero a un búfer que contiene la clave que se va a usar para el hash o MAC. El parámetro cbSecret contiene el tamaño de este búfer. Esta clave solo se aplica a los algoritmos hash abiertos por la función BCryptOpenAlgorithmProvider mediante la marca BCRYPT_ALG_HANDLE_HMAC . De lo contrario, establezca este parámetro en NULL.

La misma clave se usa para todos los elementos de la matriz.

cbSecret

ULONG[in]

Tamaño, en bytes, del búfer pbSecret . Si no se usa ninguna clave, establezca este parámetro en cero (0).

dwFlags

ULONG[in]

Marcas que modifican el comportamiento de la función. Puede ser cero o los valores siguientes. Los objetos de varios hash siempre son reutilizables y siempre se comportan como si se pasara el BCRYPT_HASH_REUSABLE_FLAG . Esta marca se admite aquí para la coherencia.

Valor	Significado
BCRYPT_HASH_REUSABLE_FLAG	Crea un objeto hash reutilizable. El objeto se puede usar para una nueva operación hash inmediatamente después de llamar a BCryptFinishHash. Para obtener más información, consulte Creación de un hash con CNG.

Valor devuelto

Devuelve un código de estado que indica el éxito o error de la función. Si el método se realiza correctamente, devolverá STATUS_SUCCESS. Para ver otros valores NTSTATUS , vea Valores NTSTATUS.

Comentarios

Internamente, los cálculos hash paralelos se realizan mediante instrucciones de varios datos (SIMD) de instrucción única con hasta 8 cálculos paralelos a la vez, según el algoritmo hash y las características de CPU disponibles. Para maximizar el rendimiento, se recomienda que el autor de la llamada proporcione al menos ocho cálculos que se pueden procesar en paralelo.

Para los cálculos de longitud desigual, proporcionar más cálculos en paralelo permite a la implementación programar mejor los cálculos en los registros de CPU. Esto puede proporcionar una ventaja de rendimiento. Para obtener un rendimiento óptimo, se recomienda que el autor de la llamada proporcione entre ocho y 100 cálculos. Seleccione un valor inferior en ese intervalo solo si todos los cálculos hash tienen la misma longitud.

No se admite el uso de hash múltiple para HMAC-MD2, HMAC-MD4 y GMAC.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 8.1 Update [aplicaciones de escritorio \| Aplicaciones para UWP]
Servidor mínimo compatible	Actualización de Windows Server 2008 [aplicaciones de escritorio \| Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	bcrypt.h
Library	Bcrypt.lib
Archivo DLL	Bcrypt.dll