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

Статья
03/14/2023

Функция BCryptGenRandom создает случайное число.

Синтаксис

NTSTATUS BCryptGenRandom(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [in, out] PUCHAR            pbBuffer,
  [in]      ULONG             cbBuffer,
  [in]      ULONG             dwFlags
);

Параметры

[in, out] hAlgorithm

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

[in, out] pbBuffer

Адрес буфера, получающего случайное число. Размер этого буфера задается параметром cbBuffer.

[in] cbBuffer

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

[in] dwFlags

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

Ценность	Значение
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER 0x00000001	Эта функция будет использовать число в буфере pbBuffer в качестве дополнительной энтропии для случайного числа. Если этот флаг не указан, эта функция будет использовать случайное число для энтропии. Windows 8 и более поздних версий: этот флаг игнорируется в Windows 8 и более поздних версиях.
BCRYPT_USE_SYSTEM_PREFERRED_RNG 0x00000002	Используйте алгоритм генератора случайных чисел, предпочитаемый системой. Параметр hAlgorithm должен быть NULL. BCRYPT_USE_SYSTEM_PREFERRED_RNG поддерживается только в PASSIVE_LEVELIRQL. Дополнительные сведения см. в разделе "Примечания". Windows Vista: этот флаг не поддерживается без пакета обновления 2 (SP2).

Ценность

Значение

BCRYPT_RNG_USE_ENTROPY_IN_BUFFER
0x00000001

Эта функция будет использовать число в буфере pbBuffer в качестве дополнительной энтропии для случайного числа. Если этот флаг не указан, эта функция будет использовать случайное число для энтропии.

Windows 8 и более поздних версий: этот флаг игнорируется в Windows 8 и более поздних версиях.

BCRYPT_USE_SYSTEM_PREFERRED_RNG
0x00000002

Используйте алгоритм генератора случайных чисел, предпочитаемый системой. Параметр hAlgorithm должен быть NULL.

BCRYPT_USE_SYSTEM_PREFERRED_RNG поддерживается только в PASSIVE_LEVELIRQL. Дополнительные сведения см. в разделе "Примечания".

Windows Vista: этот флаг не поддерживается без пакета обновления 2 (SP2).

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

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

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

Возвращаемый код	Описание
STATUS_SUCCESS	Функция была успешной.
STATUS_INVALID_HANDLE	Дескриптор в параметре hAlgorithm недопустим.
STATUS_INVALID_PARAMETER	Один или несколько параметров недопустимы.

Замечания

Поставщик случайных чисел по умолчанию реализует алгоритм для создания случайных чисел, которые соответствуют стандарту NIST SP800-90, в частности, CTR_DRBG части этого стандарта.

Windows Vista: до Windows Vista с пакетом обновления 1 (SP1) поставщик случайных чисел по умолчанию реализует алгоритм создания случайных чисел, которые соответствуют стандарту FIPS 186-2.

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

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

Требования

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

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