CryptGenRandom 函式 (wincrypt.h)

  • 發行項
重要 此 API 已被取代。 新的和現有的軟體應該開始使用 密碼編譯新一代 API。 Microsoft 可能會在未來的版本中移除此 API。
 
CryptGenRandom 函式會以密碼編譯隨機位元組填滿緩衝區。

語法

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

參數

[in] hProv

呼叫 CryptAcquireContext 所建立的密碼編譯服務提供者 (CSP) 句柄。

[in] dwLen

要產生的隨機數據位元組數目。

[in, out] pbBuffer

要接收傳回數據的緩衝區。 這個緩衝區長度至少必須是 dwLen 位元組。

或者，應用程式可以使用數據填滿此緩衝區，以作為輔助隨機種子使用。

傳回值

如果函式成功，則傳回值為非零 (TRUE) 。

如果函式失敗，則傳回值為零， (FALSE) 。 如需擴充錯誤資訊，請呼叫 GetLastError。

由 「NTE」 開頭的錯誤碼是由所使用的特定 CSP 所產生。 下表列出一些可能的錯誤碼。

傳回碼 Description
ERROR_INVALID_HANDLE
 其中一個參數指定無效的句柄。
ERROR_INVALID_PARAMETER
 其中一個參數包含無效的值。 這通常是無效的指標。
NTE_BAD_UID
 hProv 參數不包含有效的內容句柄。
NTE_FAIL
 函式以非預期的方式失敗。

備註

此函式所產生的數據是密碼編譯隨機的。 它比一般隨機數產生器所產生的數據更隨機，例如隨附於 C 編譯程式的數據。

此函式通常用於產生隨機 初始化向量 和 salt 值。

軟體隨機數產生器基本上的運作方式相同。 其開頭為隨機數，稱為種子，然後使用演算法來根據該隨機位產生虛擬隨機序列。 此程式的最困難部分是取得真正隨機的種子。 這通常是根據使用者輸入延遲，或來自一或多個硬體元件的抖動。

使用 Microsoft CSP 時， CryptGenRandom 會使用其他安全性元件所使用的相同隨機數產生器。 這可讓許多程式參與整個系統的種子。 CryptoAPI 會與每個使用者儲存中繼隨機種子。 為了形成隨機數產生器的種子，呼叫的應用程式會提供它可能有的位，例如滑鼠或鍵盤計時輸入，然後結合預存種子和各種系統數據和用戶數據，例如進程標識碼和線程標識碼、系統時鐘、系統時間、系統計數器、 記憶體狀態、可用磁碟叢集、哈希用戶環境區塊。 此結果用來植入虛擬隨機數產生器， (PRNG) 。 在 Windows Vista 的 Service Pack 1 (SP1) 和更新版本中，會使用 NIST 特殊發行集 800-90 中指定的 AES 計數器模式 PRNG 實作。 在 Windows Vista、Windows Storage Server 2003 和 Windows XP 中，會使用美國聯邦資訊處理標準 (FIPS) 186-2 中指定的 PRNG。 如果應用程式可以存取良好的隨機來源，則可以先將 pbBuffer 緩衝區填入一些隨機數據，然後再呼叫 CryptGenRandom。 然後，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
程式庫 Advapi32.lib
Dll Advapi32.dll

另請參閱

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

金鑰產生和 Exchange 函式