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

  • Статья

Функция 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).

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

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

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

Код возврата Описание
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]
Целевая платформа Windows
Header bcrypt.h
Библиотека Bcrypt.lib или Cng.lib(для режима ядра)
DLL Bcrypt.dll