Функция CryptGenRandom (wincrypt.h)

Статья
08/27/2023

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

Функция CryptGenRandom заполняет буфер криптографически случайными байтами.

Синтаксис

BOOL CryptGenRandom(
  [in]      HCRYPTPROV hProv,
  [in]      DWORD      dwLen,
  [in, out] BYTE       *pbBuffer
);

Параметры

[in] hProv

Дескриптор поставщика служб шифрования (CSP), созданного при вызове CryptAcquireContext.

[in] dwLen

Число байтов случайных данных, которые необходимо создать.

[in, out] pbBuffer

Буфер для получения возвращаемых данных. Длина этого буфера должна быть не менее dwLen-байтов .

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

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

Если функция выполнена успешно, возвращается ненулевое значение (TRUE).

Если функция завершается сбоем, возвращаемое значение равно нулю (FALSE). Чтобы получить дополнительные сведения об ошибке, вызовите Метод GetLastError.

Коды ошибок, предваряемые "NTE", создаются конкретным поставщиком служб CSP. Некоторые возможные коды ошибок перечислены в следующей таблице.

Код возврата	Описание
ERROR_INVALID_HANDLE	Один из параметров указывает недопустимый дескриптор.
ERROR_INVALID_PARAMETER	Один из параметров содержит недопустимое значение. Чаще всего это недопустимый указатель.
NTE_BAD_UID	Параметр hProv не содержит допустимый дескриптор контекста.
NTE_FAIL	Сбой функции каким-то неожиданным образом.

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

Эта функция часто используется для создания случайных векторов инициализации и значений соли.

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

В microsoft CSP CryptGenRandom использует тот же генератор случайных чисел, что и другие компоненты безопасности. Это позволяет многочисленным процессам вносить свой вклад в общесистемное начальное значение. CryptoAPI хранит промежуточное случайное начальное значение для каждого пользователя. Чтобы сформировать начальное значение для генератора случайных чисел, вызывающее приложение предоставляет биты, которые могут быть у него, например, ввод времени мыши или клавиатуры, которые затем объединяются с хранимым начальным значением и различными системными и пользовательскими данными, такими как идентификатор процесса и идентификатор потока, системные часы, системное время, системный счетчик. состояние памяти, кластеры свободных дисков, хэшированные блоки пользовательской среды. Этот результат используется для заполнения генератора псевдослучайных чисел (PRNG). В Windows Vista с пакетом обновления 1 (SP1) и более поздних версий используется реализация режима счетчика AES PRNG, указанного в специальной публикации NIST 800-90. В Windows Vista, Windows Storage Server 2003 и Windows XP используется PRNG, указанный в федеральном стандарте обработки информации (FIPS) 186-2. Если приложение имеет доступ к хорошему случайному источнику, оно может заполнить буфер pbBuffer случайными данными перед вызовом CryptGenRandom. Затем поставщик служб CSP использует эти данные для дальнейшей случайной выборки внутреннего начального значения. Можно опустить этап инициализации буфера pbBuffer перед вызовом CryptGenRandom.

Примеры

В следующем примере показано создание 8 случайных байтов. Их можно использовать для создания криптографических ключей или для любого приложения, использующего случайные числа. Пример, включающий полный контекст для этого примера, см. в разделе Пример программы C: дублирование ключа сеанса.

//--------------------------------------------------------------------
// Declare and initialize variables.

HCRYPTPROV   hCryptProv;
BYTE         pbData[16];

//--------------------------------------------------------------------
//  This code assumes that a cryptographic context has been acquired 
//  For code details, see "Example C Program: Duplicating a Session 
//  Key."

//--------------------------------------------------------------------
// Generate a random initialization vector.

if(CryptGenRandom(
   hCryptProv, 
   8, 
   pbData)) 
{
     printf("Random sequence generated. \n");
}
else
{
     printf("Error during CryptGenRandom.\n");
     exit(1);
}

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	wincrypt.h
Библиотека	Advapi32.lib
DLL	Advapi32.dll

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

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

Функции создания ключей и обмена

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