CryptGenRandom 函数 (wincrypt.h)

  • 项目
重要 此 API 已弃用。 新的和现有的软件应开始使用 加密下一代 API。 Microsoft 可能会在将来的版本中删除此 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 存储每个用户的中间随机种子。 为了形成随机数生成器的种子，调用应用程序提供它可能具有的位（例如鼠标或键盘计时输入），然后与存储的种子和各种系统数据和用户数据（例如进程 ID 和线程 ID、系统时钟、系统时间、系统计数器）组合在一起， 内存状态、可用磁盘群集、哈希用户环境块。 此结果用于将伪随机数生成器 (PRNG) 种子。 在具有 Service Pack 1 的 Windows Vista (SP1) 及更高版本中，使用 NIST Special Publication 800-90 中指定的基于 AES 计数器模式的 PRNG 的实现。 在 Windows Vista、Windows Storage Server 2003 和 Windows XP 中，使用联邦信息处理标准 (FIPS) 186-2 中指定的 PRNG。 如果应用程序有权访问良好的随机源，则可以在调用 CryptGenRandom 之前使用一些随机数据填充 pbBuffer 缓冲区。 然后，CSP 使用此数据进一步随机化其内部种子。 在调用 CryptGenRandom 之前，可以省略初始化 pbBuffer 缓冲区的步骤。

示例

以下示例演示生成 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
标头 wincrypt.h
Library Advapi32.lib
DLL Advapi32.dll

另请参阅

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

密钥生成和交换函数