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

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

Синтаксис

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

Параметры

[in, out] hAlgorithm

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

[out] phHash

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

[out, optional] pbHashObject

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

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

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

[in] cbHashObject

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

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

[in, optional] pbSecret

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

Чтобы вычислить хэш, задайте для этого параметра значение NULL.

[in] cbSecret

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

[in] dwFlags

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

Ценность	Значение
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_NOT_SUPPORTED	Поставщик алгоритмов, указанный параметром hAlgorithm , не поддерживает хэш-интерфейс или ИНТЕРФЕЙС MAC.

Замечания

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

Вызывающий объект должен освободить phHash с BCryptDeskhash , когда объект больше не используется.

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

Требования

Требование	Ценность
Минимальный поддерживаемый клиент	Windows Vista [классические приложения | Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2008 [классические приложения | Приложения UWP]
целевая платформа	Виндоус
Header	bcrypt.h
Library	Bcrypt.lib
DLL	Bcrypt.dll

См. также

BCryptDuplicateHash

BCryptHashData

BCryptFinishHash

BCryptDeskHash