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

Статья
02/23/2024

Функция BCryptCreateHash вызывается для создания объекта хэша или кода проверки подлинности сообщений (MAC).

Синтаксис

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

Параметры

[in, out] hAlgorithm

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

[out] phHash

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

[out] pbHashObject

Указатель на буфер, который получает объект hash или MAC. Параметр cbHashObject содержит размер этого буфера. Требуемый размер этого буфера можно получить, вызвав функцию BCryptGetProperty для получения свойства BCRYPT_OBJECT_LENGTH . Это обеспечит размер объекта хэша или MAC для указанного алгоритма.

Эту память можно освободить только после того, как дескриптор, на который указывает параметр phHash , будет уничтожен.

Если значение этого параметра равно NULL , а значение параметра cbHashObject равно нулю, память для хэш-объекта выделяется и освобождается этой функцией. Windows 7: Эта функция управления памятью доступна начиная с Windows 7.

[in, optional] cbHashObject

Размер буфера pbHashObject в байтах.

Если значение этого параметра равно нулю, а значение параметра pbHashObject равно NULL, память для объекта ключа выделяется и освобождается этой функцией. Windows 7: Эта функция управления памятью доступна начиная с Windows 7.

[in, optional] pbSecret

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

[in] cbSecret

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

[in] dwFlags

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

Значение	Значение
BCRYPT_HASH_REUSABLE_FLAG	Создает повторно используемый объект хэширования. Объект можно использовать для новой операции хэширования сразу после вызова BCryptFinishHash. Дополнительные сведения см. в разделе Создание хэша с помощью CNG. Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista: Этот флаг не поддерживается.

Значение

BCRYPT_HASH_REUSABLE_FLAG

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

Windows Server 2008 R2, Windows 7, Windows Server 2008 и Windows Vista: Этот флаг не поддерживается.

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

Возвращает код состояния, указывающий на успешное или неудачное выполнение функции.

Возможные коды возврата включают, помимо прочего, следующие.

Код возврата	Описание
STATUS_SUCCESS	Функция выполнена успешно.
STATUS_BUFFER_TOO_SMALL	Размер хэш-объекта, указанного параметром cbHashObject , недостаточно велик для хранения хэш-объекта.
STATUS_INVALID_HANDLE	Дескриптор алгоритма в параметре hAlgorithm недопустим .
STATUS_INVALID_PARAMETER	Один или несколько параметров являются недопустимыми.
STATUS_NOT_SUPPORTED	Поставщик алгоритма, указанный параметром hAlgorithm , не поддерживает хэш-интерфейс.

В зависимости от того, какие режимы процессора поддерживает поставщик, BCryptCreateHash можно вызывать из пользовательского режима или режима ядра. Вызывающие функции режима ядра могут выполняться в PASSIVE_LEVELIRQL или DISPATCH_LEVEL IRQL. Если текущий уровень IRQL DISPATCH_LEVEL, дескриптор, указанный в параметре hAlgorithm , должен быть открыт с помощью флага BCRYPT_PROV_DISPATCH , а все указатели, передаваемые в функцию BCryptCreateHash , должны ссылаться на непагрегированную (или заблокированную) память.

Чтобы вызвать эту функцию в режиме ядра, используйте Cng.lib, который входит в состав пакета средств разработки драйверов (DDK). Дополнительные сведения см. в разделе WDK и средства разработчика. Windows Server 2008 и Windows Vista: Чтобы вызвать эту функцию в режиме ядра, используйте Ksecdd.lib.

Требования

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

См. также раздел

BCryptDeкишхаш

Поделиться через