CryptGenRandom 関数 (wincrypt.h)

[アーティクル]
08/27/2023

大事な この 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 バイトである必要があります。

必要に応じて、アプリケーションは、補助ランダムシードとして使用するデータでこのバッファーを埋めることができます。

戻り値

関数が成功した場合、戻り値は 0 以外 (TRUE) になります。

関数が失敗した場合、戻り値は 0 (FALSE) になります。拡張エラー情報については、 GetLastError を呼び出します。

"NTE" の前にあるエラーコードは、使用されている特定の CSP によって生成されます。考えられるエラーコードの一部を次の表に示します。

リターンコード	説明
ERROR_INVALID_HANDLE	パラメーターの 1 つは、無効なハンドルを指定します。
ERROR_INVALID_PARAMETER	パラメーターの 1 つに無効な値が含まれています。これは、ほとんどの場合、無効なポインターです。
NTE_BAD_UID	hProv パラメーターに有効なコンテキストハンドルが含まれていません。
NTE_FAIL	関数が予期しない方法で失敗しました。

注釈

この関数によって生成されるデータは、暗号的にランダムです。これは、C コンパイラに付属するものなど、一般的な乱数ジェネレーターによって生成されるデータよりもはるかにランダムです。

この関数は、多くの場合、ランダムな初期化ベクトルとソルト値を生成するために使用されます。

ソフトウェア乱数ジェネレーターは、基本的に同じ方法で動作します。これらはシードと呼ばれる乱数から始まり、アルゴリズムを使用して、それに基づいてビットの擬似ランダムシーケンスを生成します。このプロセスの最も困難な部分は、本当にランダムなシードを取得することです。これは通常、ユーザー入力の待機時間、または 1 つ以上のハードウェアコンポーネントからのジッターに基づいています。

Microsoft CSP では、 CryptGenRandom は他のセキュリティコンポーネントで使用されるのと同じ乱数ジェネレーターを使用します。これにより、多数のプロセスがシステム全体のシードに貢献できるようになります。 CryptoAPI は、すべてのユーザーに中間ランダムシードを格納します。乱数ジェネレーターのシードを形成するために、呼び出し元のアプリケーションは、それが持っている可能性のあるビット (たとえば、マウスやキーボードのタイミング入力) を提供し、格納されているシードとさまざまなシステムデータと、プロセス ID やスレッド ID、システムクロック、システム時刻、システムカウンターなどのユーザーデータの両方と組み合わせて使用します。メモリの状態、空きディスククラスター、ハッシュされたユーザー環境ブロック。この結果は、擬似乱数ジェネレーター (PRNG) のシード処理に使用されます。 Windows Vista Service Pack 1 (SP1) 以降では、NIST Special Publication 800-90 で指定された AES カウンターモードベースの PRNG の実装が使用されます。 Windows Vista、Windows Storage Server 2003、および Windows XP では、Federal Information Processing Standard (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