ホーム › Security.Cryptography › BCryptGenRandom

BCryptGenRandom

関数

CNGを使い暗号学的に安全な乱数バイト列を生成する。

DLLbcrypt.dll呼出規約winapi対応OSWindows Vista 以降

シグネチャ

// bcrypt.dll
#include <windows.h>

NTSTATUS BCryptGenRandom(
    BCRYPT_ALG_HANDLE hAlgorithm,   // optional
    BYTE* pbBuffer,
    DWORD cbBuffer,
    BCRYPTGENRANDOM_FLAGS dwFlags
);

パラメーター

名前

型

方向

説明

hAlgorithm

BCRYPT_ALG_HANDLE

inoptional

BCryptOpenAlgorithmProvider 関数で作成したアルゴリズムプロバイダーのハンドル。プロバイダー作成時に指定したアルゴリズムは、乱数生成インターフェイスをサポートしている必要があります。

pbBuffer

BYTE*

out

乱数を受け取るバッファーのアドレス。このバッファーのサイズは cbBuffer パラメーターで指定します。

cbBuffer

DWORD

pbBuffer バッファーのサイズ(バイト単位)。

dwFlags

BCRYPTGENRANDOM_FLAGS

この関数の動作を変更するフラグのセット。このパラメーターには 0、または次の値を指定できます。

値

意味

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_LEVEL IRQL でのみサポートされます。詳細については「解説」を参照してください。

Windows Vista: このフラグは SP2 なしではサポートされません。

戻り値の型: NTSTATUS

公式ドキュメント

乱数を生成します。

戻り値

関数の成否を示すステータスコードを返します。

返される可能性のあるコードには、次のものが含まれますが、これらに限定されません。

戻り値	説明
STATUS_SUCCESS	関数は成功しました。
STATUS_INVALID_HANDLE	hAlgorithm パラメーターのハンドルが無効です。
STATUS_INVALID_PARAMETER	1 つ以上のパラメーターが無効です。

解説(Remarks)

既定の乱数プロバイダーは、NIST SP800-90 標準、具体的にはその標準の CTR_DRBG 部分に準拠した乱数生成アルゴリズムを実装しています。

Windows Vista: Windows Vista with Service Pack 1 (SP1) より前では、既定の乱数プロバイダーは FIPS 186-2 標準に準拠した乱数生成アルゴリズムを実装しています。

サポートされているアルゴリズムプロバイダーを使用する場合、BCryptGenRandom はユーザーモードまたはカーネルモードのいずれからでも呼び出すことができます。カーネルモードの呼び出し元は、PASSIVE_LEVEL IRQL または DISPATCH_LEVEL IRQL のいずれかで実行できます。現在の IRQL レベルが DISPATCH_LEVEL の場合、hAlgorithm パラメーターで指定するハンドルは BCRYPT_PROV_DISPATCH フラグを使用して開かれている必要があり、BCryptGenRandom 関数に渡すすべてのポインターはページング不可(またはロックされた)メモリを参照している必要があります。Windows Vista: Microsoft プロバイダーは DISPATCH_LEVEL での呼び出しをサポートしていません。

この関数をカーネルモードで呼び出すには、Driver Development Kit (DDK) の一部である Cng.lib を使用します。Windows Server 2008 および Windows Vista: この関数をカーネルモードで呼び出すには、Ksecdd.lib を使用します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での呼び出し定義

// bcrypt.dll
#include <windows.h>

NTSTATUS BCryptGenRandom(
    BCRYPT_ALG_HANDLE hAlgorithm,   // optional
    BYTE* pbBuffer,
    DWORD cbBuffer,
    BCRYPTGENRANDOM_FLAGS dwFlags
);

[DllImport("bcrypt.dll", ExactSpelling = true)]
static extern int BCryptGenRandom(
    IntPtr hAlgorithm,   // BCRYPT_ALG_HANDLE optional
    IntPtr pbBuffer,   // BYTE* out
    uint cbBuffer,   // DWORD
    uint dwFlags   // BCRYPTGENRANDOM_FLAGS
);

<DllImport("bcrypt.dll", ExactSpelling:=True)>
Public Shared Function BCryptGenRandom(
    hAlgorithm As IntPtr,   ' BCRYPT_ALG_HANDLE optional
    pbBuffer As IntPtr,   ' BYTE* out
    cbBuffer As UInteger,   ' DWORD
    dwFlags As UInteger   ' BCRYPTGENRANDOM_FLAGS
) As Integer
End Function

' hAlgorithm : BCRYPT_ALG_HANDLE optional
' pbBuffer : BYTE* out
' cbBuffer : DWORD
' dwFlags : BCRYPTGENRANDOM_FLAGS
Declare PtrSafe Function BCryptGenRandom Lib "bcrypt" ( _
    ByVal hAlgorithm As LongPtr, _
    ByVal pbBuffer As LongPtr, _
    ByVal cbBuffer As Long, _
    ByVal dwFlags As Long) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

BCryptGenRandom = ctypes.windll.bcrypt.BCryptGenRandom
BCryptGenRandom.restype = ctypes.c_int
BCryptGenRandom.argtypes = [
    wintypes.HANDLE,  # hAlgorithm : BCRYPT_ALG_HANDLE optional
    ctypes.POINTER(ctypes.c_ubyte),  # pbBuffer : BYTE* out
    wintypes.DWORD,  # cbBuffer : DWORD
    wintypes.DWORD,  # dwFlags : BCRYPTGENRANDOM_FLAGS
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('bcrypt.dll')
BCryptGenRandom = Fiddle::Function.new(
  lib['BCryptGenRandom'],
  [
    Fiddle::TYPE_VOIDP,  # hAlgorithm : BCRYPT_ALG_HANDLE optional
    Fiddle::TYPE_VOIDP,  # pbBuffer : BYTE* out
    -Fiddle::TYPE_INT,  # cbBuffer : DWORD
    -Fiddle::TYPE_INT,  # dwFlags : BCRYPTGENRANDOM_FLAGS
  ],
  Fiddle::TYPE_INT)

#[link(name = "bcrypt")]
extern "system" {
    fn BCryptGenRandom(
        hAlgorithm: *mut core::ffi::c_void,  // BCRYPT_ALG_HANDLE optional
        pbBuffer: *mut u8,  // BYTE* out
        cbBuffer: u32,  // DWORD
        dwFlags: u32  // BCRYPTGENRANDOM_FLAGS
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("bcrypt.dll")]
public static extern int BCryptGenRandom(IntPtr hAlgorithm, IntPtr pbBuffer, uint cbBuffer, uint dwFlags);
"@
$api = Add-Type -MemberDefinition $sig -Name 'bcrypt_BCryptGenRandom' -Namespace Win32 -PassThru
# $api::BCryptGenRandom(hAlgorithm, pbBuffer, cbBuffer, dwFlags)

#uselib "bcrypt.dll"
#func global BCryptGenRandom "BCryptGenRandom" sptr, sptr, sptr, sptr
; BCryptGenRandom hAlgorithm, varptr(pbBuffer), cbBuffer, dwFlags   ; 戻り値は stat
; hAlgorithm : BCRYPT_ALG_HANDLE optional -> "sptr"
; pbBuffer : BYTE* out -> "sptr"
; cbBuffer : DWORD -> "sptr"
; dwFlags : BCRYPTGENRANDOM_FLAGS -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "bcrypt.dll"
#cfunc global BCryptGenRandom "BCryptGenRandom" sptr, var, int, int
; res = BCryptGenRandom(hAlgorithm, pbBuffer, cbBuffer, dwFlags)
; hAlgorithm : BCRYPT_ALG_HANDLE optional -> "sptr"
; pbBuffer : BYTE* out -> "var"
; cbBuffer : DWORD -> "int"
; dwFlags : BCRYPTGENRANDOM_FLAGS -> "int"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "bcrypt.dll"
#cfunc global BCryptGenRandom "BCryptGenRandom" sptr, sptr, int, int
; res = BCryptGenRandom(hAlgorithm, varptr(pbBuffer), cbBuffer, dwFlags)
; hAlgorithm : BCRYPT_ALG_HANDLE optional -> "sptr"
; pbBuffer : BYTE* out -> "sptr"
; cbBuffer : DWORD -> "int"
; dwFlags : BCRYPTGENRANDOM_FLAGS -> "int"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。