Fungsi BCryptGenRandom (bcrypt.h)

Artikel
01/27/2024

Fungsi BCryptGenRandom menghasilkan angka acak.

Sintaks

NTSTATUS BCryptGenRandom(
  [in, out] BCRYPT_ALG_HANDLE hAlgorithm,
  [in, out] PUCHAR            pbBuffer,
  [in]      ULONG             cbBuffer,
  [in]      ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Handel penyedia algoritma yang dibuat dengan menggunakan fungsi BCryptOpenAlgorithmProvider . Algoritma yang ditentukan ketika penyedia dibuat harus mendukung antarmuka generator angka acak.

[in, out] pbBuffer

Alamat buffer yang menerima angka acak. Ukuran buffer ini ditentukan oleh parameter cbBuffer .

[in] cbBuffer

Ukuran, dalam byte, dari buffer pbBuffer .

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Parameter ini bisa nol atau nilai berikut.

Nilai	Makna
BCRYPT_RNG_USE_ENTROPY_IN_BUFFER 0x00000001	Fungsi ini akan menggunakan angka dalam buffer pbBuffer sebagai entropi tambahan untuk angka acak. Jika bendera ini tidak ditentukan, fungsi ini akan menggunakan angka acak untuk entropi. Windows 8 dan yang lebih baru: Bendera ini diabaikan di Windows 8 dan yang lebih baru.
BCRYPT_USE_SYSTEM_PREFERRED_RNG 0x00000002	Gunakan algoritma generator angka acak pilihan sistem. Parameter hAlgorithm harus NULL. BCRYPT_USE_SYSTEM_PREFERRED_RNG hanya didukung di PASSIVE_LEVELIRQL. Untuk informasi selengkapnya, lihat Keterangan. Windows Vista: Bendera ini tidak didukung tanpa SP2.

Nilai

Makna

BCRYPT_RNG_USE_ENTROPY_IN_BUFFER
0x00000001

Fungsi ini akan menggunakan angka dalam buffer pbBuffer sebagai entropi tambahan untuk angka acak. Jika bendera ini tidak ditentukan, fungsi ini akan menggunakan angka acak untuk entropi.

Windows 8 dan yang lebih baru: Bendera ini diabaikan di Windows 8 dan yang lebih baru.

BCRYPT_USE_SYSTEM_PREFERRED_RNG
0x00000002

Gunakan algoritma generator angka acak pilihan sistem. Parameter hAlgorithm harus NULL.

BCRYPT_USE_SYSTEM_PREFERRED_RNG hanya didukung di PASSIVE_LEVELIRQL. Untuk informasi selengkapnya, lihat Keterangan.

Windows Vista: Bendera ini tidak didukung tanpa SP2.

Nilai kembali

Mengembalikan kode status yang menunjukkan keberhasilan atau kegagalan fungsi.

Kemungkinan kode pengembalian termasuk, tetapi tidak terbatas pada, berikut ini.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Fungsi berhasil.
STATUS_INVALID_HANDLE	Handel dalam parameter hAlgorithm tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.

Keterangan

Penyedia angka acak default mengimplementasikan algoritma untuk menghasilkan angka acak yang sesuai dengan standar NIST SP800-90, khususnya bagian CTR_DRBG dari standar tersebut.

Windows Vista: Sebelum Windows Vista dengan Paket Layanan 1 (SP1) penyedia angka acak default menerapkan algoritma untuk menghasilkan angka acak yang sesuai dengan standar FIPS 186-2.

Bergantung pada mode prosesor apa yang didukung penyedia, BCryptGenRandom dapat dipanggil baik dari mode pengguna atau mode kernel. Pemanggil mode kernel dapat mengeksekusi baik di PASSIVE_LEVEL IRQL atau DISPATCH_LEVEL IRQL. Jika tingkat IRQL saat ini DISPATCH_LEVEL, handel yang disediakan dalam parameter hAlgorithm harus dibuka dengan menggunakan bendera BCRYPT_PROV_DISPATCH , dan setiap pointer yang diteruskan ke fungsi BCryptGenRandom harus merujuk ke memori yang tidak di-patah (atau dikunci). Windows Vista: Penyedia Microsoft tidak mendukung panggilan di DISPATCH_LEVEL.

Untuk memanggil fungsi ini dalam mode kernel, gunakan Cng.lib, yang merupakan bagian dari Driver Development Kit (DDK). Windows Server 2008 dan Windows Vista: Untuk memanggil fungsi ini dalam mode kernel, gunakan Ksecdd.lib.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [aplikasi desktop \| Aplikasi UWP]
Server minimum yang didukung	Windows Server 2008 [aplikasi desktop \| Aplikasi UWP]
Target Platform	Windows
Header	bcrypt.h
Pustaka	Bcrypt.lib atau Cng.lib(Untuk mode Kernel)
DLL	Bcrypt.dll