BCryptCreateMultiHash, fonction (bcrypt.h)

Article
03/23/2023

La fonction BCryptCreateMultiHash crée un état multi hachage qui permet le calcul parallèle de plusieurs opérations de hachage. Cet état de hachage multiple est utilisé par la fonction BCryptProcessMultiOperations . L’état multi hachage peut être considéré comme un tableau d’objets de hachage, chacun d’entre eux équivalent à un objet créé par BCryptCreateHash.

Les calculs parallèles peuvent considérablement augmenter le débit global, au détriment d’une latence accrue pour les calculs individuels.

Les calculs de hachage parallèles sont actuellement implémentés uniquement pour SHA-256, SHA-384 et SHA-512. D’autres algorithmes de hachage peuvent être utilisés avec l’API de calcul parallèle, mais ils s’exécutent au débit des opérations de hachage séquentielles. L’ensemble d’algorithmes de hachage qui peuvent tirer parti des calculs parallèles peut changer dans les mises à jour futures.

Syntaxe

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

Paramètres

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

Handle d’algorithme utilisé pour tous les états de hachage dans le tableau multi hachage. Le handle d’algorithme doit avoir été ouvert avec le BCYRPT_MULTI_FLAG passé à la fonction BCryptOpenAlgorithmProvider . L’appelant peut également utiliser les pseudo-handles.

phHash

BCRYPT_HASH_HANDLE* [out]

Pointeur vers une valeur BCRYPT_HASH_HANDLE qui reçoit un handle qui représente l’état multi hachage. Ce handle est utilisé dans les opérations suivantes telles que BCryptProcessMultiOperations. Une fois que vous avez terminé d’utiliser ce handle, relâchez-le en le transmettant à la fonction BCryptDestroyHash .

nHashes

ULONG[in]

Nombre d’éléments dans le tableau. L’état multi hachage créé par cette fonction est capable d’effectuer des calculs parallèles sur nHashs différents états de hachage.

pbHashObject

PUCHAR[out]

Pointeur vers une mémoire tampon qui reçoit l’état multi hachage.

La taille peut être calculée à partir des membres cbPerObject et cbPerElement de la structure BCRYPT_MULTI_OBJECT_LENGTH_STRUCT . La valeur est la suivante : cbPerObject + (number of hash states) * cbPerElement.

Si pbHashObject est NULL et que cbHashObject a la valeur zéro (0), la mémoire tampon d’objet est automatiquement allouée.

cbHashObject

ULONG[in]

Taille de la mémoire tampon pbHashObject , ou zéro (0) si pbHashObject est NULL.

pbSecret

PUCHAR[in]

Pointeur vers une mémoire tampon qui contient la clé à utiliser pour le hachage ou mac. Le paramètre cbSecret contient la taille de cette mémoire tampon. Cette clé s’applique uniquement aux algorithmes de hachage ouverts par la fonction BCryptOpenAlgorithmProvider à l’aide de l’indicateur BCRYPT_ALG_HANDLE_HMAC . Sinon, définissez ce paramètre sur NULL.

La même clé est utilisée pour tous les éléments du tableau.

cbSecret

ULONG[in]

Taille, en octets, de la mémoire tampon pbSecret . Si aucune clé n’est utilisée, définissez ce paramètre sur zéro (0).

dwFlags

ULONG[in]

Indicateurs qui modifient le comportement de la fonction. Il peut s’agir de zéro ou des valeurs ci-dessous. Les objets multi hachage sont toujours réutilisables et se comportent toujours comme si le BCRYPT_HASH_REUSABLE_FLAG avait été passé. Cet indicateur est pris en charge ici à des fins de cohérence.

Valeur	Signification
BCRYPT_HASH_REUSABLE_FLAG	Crée un objet de hachage réutilisable. L’objet peut être utilisé pour une nouvelle opération de hachage immédiatement après l’appel de BCryptFinishHash. Pour plus d’informations, consultez Création d’un hachage avec CNG.

Valeur retournée

Retourne un code status qui indique la réussite ou l’échec de la fonction. Si la méthode réussit, elle retourne STATUS_SUCCESS. Pour obtenir d’autres valeurs NTSTATUS , consultez Valeurs NTSTATUS.

Remarques

En interne, les calculs de hachage parallèles sont effectués à l’aide d’instructions SIMD (single-instruction multiple-data) avec jusqu’à 8 calculs parallèles à la fois, en fonction de l’algorithme de hachage et des fonctionnalités du processeur disponibles. Pour optimiser les performances, nous recommandons à l’appelant de fournir au moins huit calculs qui peuvent être traités en parallèle.

Pour les calculs de longueur inégale, le fait de fournir davantage de calculs en parallèle permet à l’implémentation de mieux planifier les calculs entre les registres d’UC. Cela peut fournir un avantage de débit. Pour un débit optimal, nous recommandons que l’appelant fournisse entre huit et 100 calculs. Sélectionnez une valeur inférieure dans cette plage uniquement si tous les calculs de hachage ont la même longueur.

Le hachage multiple n’est pas pris en charge pour HMAC-MD2, HMAC-MD4 et GMAC.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Mise à jour Windows 8.1 [applications de bureau \| Applications UWP]
Serveur minimal pris en charge	Windows Server 2008 Update [applications de bureau \| Applications UWP]
Plateforme cible	Windows
En-tête	bcrypt.h
Bibliothèque	Bcrypt.lib
DLL	Bcrypt.dll