Функция BCryptCreateMultiHash (bcrypt.h)

Статья
06/01/2023

Функция BCryptCreateMultiHash создает состояние с несколькими хэшами, которое позволяет параллельно вычислять несколько хэш-операций. Это состояние с несколькими хэшами используется функцией BCryptProcessMultiOperations . Состояние с несколькими хэшами можно рассматривать как массив хэш-объектов, каждый из которых эквивалентен одному, созданному BCryptCreateHash.

Параллельные вычисления могут значительно увеличить общую пропускную способность за счет увеличения задержки для отдельных вычислений.

Параллельные хэш-вычисления в настоящее время реализованы только для SHA-256, SHA-384 и SHA-512. Другие хэш-алгоритмы можно использовать с API параллельных вычислений, но они выполняются с пропускной способностью последовательных хэш-операций. Набор хэш-алгоритмов, которые могут воспользоваться преимуществами параллельных вычислений, может измениться в будущих обновлениях.

Синтаксис

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

Параметры

hAlgorithm

BCRYPT_ALG_HANDLE[in, out]

Дескриптор алгоритма, используемый для всех хэш-состояний в массиве с несколькими хэшами. Дескриптор алгоритма должен быть открыт с BCYRPT_MULTI_FLAG передан в функцию BCryptOpenAlgorithmProvider . Кроме того, вызывающий объект может использовать псевдо-дескрипторы.

phHash

BCRYPT_HASH_HANDLE* [out]

Указатель на значение BCRYPT_HASH_HANDLE , получающее дескриптор, представляющий состояние с несколькими хэшами. Этот дескриптор используется в последующих операциях, таких как BCryptProcessMultiOperations. Завершив использование этого дескриптора, отпустите его, передав его в функцию BCryptDeographyHash .

nHashes

ULONG[in]

Количество элементов в массиве. Состояние с несколькими хэшами, создаваемое этой функцией, может выполнять параллельные вычисления для различных хэш-состояний nHashes .

pbHashObject

PUCHAR[out]

Указатель на буфер, получающий состояние с несколькими хэшами.

Размер можно вычислить из элементов cbPerObject и cbPerElementструктуры BCRYPT_MULTI_OBJECT_LENGTH_STRUCT . Значением является следующее: cbPerObject + (number of hash states) * cbPerElement.

Если pbHashObject имеет значение NULL и cbHashObject имеет нулевое значение (0), буфер объектов выделяется автоматически.

cbHashObject

ULONG[in]

Размер буфера pbHashObject или нуль (0), если pbHashObject имеет значение NULL.

pbSecret

PUCHAR[in]

Указатель на буфер, содержащий ключ, используемый для хэша или MAC-адреса. Параметр cbSecret содержит размер этого буфера. Этот ключ применяется только к хэш-алгоритмам, открытым функцией BCryptOpenAlgorithmProvider с помощью флага BCRYPT_ALG_HANDLE_HMAC . В противном случае задайте для этого параметра значение NULL.

Один и тот же ключ используется для всех элементов массива.

cbSecret

ULONG[in]

Размер буфера pbSecret (в байтах). Если ключ не используется, задайте для этого параметра нулевое значение (0).

dwFlags

ULONG[in]

Флаги, изменяющие поведение функции. Это может быть ноль или приведенные ниже значения. Объекты с несколькими хэшами всегда можно повторно использовать и всегда вести себя так, как если бы был передан BCRYPT_HASH_REUSABLE_FLAG . Этот флаг поддерживается здесь для обеспечения согласованности.

Значение	Значение
BCRYPT_HASH_REUSABLE_FLAG	Создает повторно используемый объект хэширования. Объект можно использовать для новой операции хэширования сразу после вызова BCryptFinishHash. Дополнительные сведения см. в разделе Создание хэша с помощью CNG.

Возвращаемое значение

Возвращает код состояния, указывающий на успешное или неудачное выполнение функции. Если метод будет выполнен успешно, он вернет STATUS_SUCCESS. Другие значения NTSTATUS см. в разделе Значения NTSTATUS.

На внутреннем уровне параллельные хэш-вычисления выполняются с помощью инструкций с одной инструкцией с несколькими данными (SIMD) с 8 параллельными вычислениями за раз, в зависимости от хэш-алгоритма и доступных функций ЦП. Чтобы повысить производительность, мы рекомендуем, чтобы вызывающий объект предоставлял по крайней мере восемь вычислений, которые можно обрабатывать параллельно.

Для вычислений с неравной длиной предоставление дополнительных вычислений в параллельном режиме позволяет реализации лучше планировать вычисления в регистрах ЦП. Это может обеспечить преимущество пропускной способности. Для оптимальной пропускной способности мы рекомендуем, чтобы вызывающий объект предоставлял от восьми до 100 вычислений. Выберите меньшее значение в этом диапазоне, только если все вычисления хэша имеют одинаковую длину.

Многохеширование не поддерживается для HMAC-MD2, HMAC-MD4 и GMAC.

Требования

Требование	Значение
Минимальная версия клиента	Windows 8.1 с обновлением [классические приложения \| Приложения UWP]
Минимальная версия сервера	Обновление Windows Server 2008 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	bcrypt.h
Библиотека	Bcrypt.lib
DLL	Bcrypt.dll