Fungsi CryptGenRandom (wincrypt.h)

Artikel
08/27/2023

Penting API ini tidak digunakan lagi. Perangkat lunak baru dan yang sudah ada harus mulai menggunakan Cryptography Next Generation API. Microsoft dapat menghapus API ini dalam rilis mendatang.

Fungsi CryptGenRandom mengisi buffer dengan byte acak kriptografis.

Sintaks

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

Parameter

[in] hProv

Menangani penyedia layanan kriptografi (CSP) yang dibuat oleh panggilan ke CryptAcquireContext.

[in] dwLen

Jumlah byte data acak yang akan dihasilkan.

[in, out] pbBuffer

Buffer untuk menerima data yang dikembalikan. Panjang buffer ini harus setidaknya dwLen byte.

Secara opsional, aplikasi dapat mengisi buffer ini dengan data untuk digunakan sebagai benih acak tambahan.

Mengembalikan nilai

Jika fungsi berhasil, nilai yang dikembalikan bukan nol (TRUE).

Jika fungsi gagal, nilai yang dikembalikan adalah nol (FALSE). Untuk informasi kesalahan yang diperluas, hubungi GetLastError.

Kode kesalahan yang diawali oleh "NTE" dihasilkan oleh CSP tertentu yang digunakan. Beberapa kemungkinan kode kesalahan tercantum dalam tabel berikut.

Menampilkan kode	Deskripsi
ERROR_INVALID_HANDLE	Salah satu parameter menentukan handel yang tidak valid.
ERROR_INVALID_PARAMETER	Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid.
NTE_BAD_UID	Parameter hProv tidak berisi handel konteks yang valid.
NTE_FAIL	Fungsi gagal dengan cara yang tidak terduga.

Keterangan

Data yang dihasilkan oleh fungsi ini acak secara kriptografis. Ini jauh lebih acak daripada data yang dihasilkan oleh generator angka acak biasa seperti yang dikirim dengan pengkompilasi C Anda.

Fungsi ini sering digunakan untuk menghasilkan vektor inisialisasi acak dan nilai garam.

Generator angka acak perangkat lunak bekerja dengan cara yang sama pada dasarnya. Mereka dimulai dengan angka acak, yang dikenal sebagai benih, dan kemudian menggunakan algoritma untuk menghasilkan urutan bit pseudo-acak berdasarkan itu. Bagian paling sulit dari proses ini adalah mendapatkan benih yang benar-benar acak. Ini biasanya didasarkan pada latensi input pengguna, atau jitter dari satu atau beberapa komponen perangkat keras.

Dengan CSP Microsoft, CryptGenRandom menggunakan generator angka acak yang sama yang digunakan oleh komponen keamanan lainnya. Ini memungkinkan banyak proses untuk berkontribusi pada benih di seluruh sistem. CryptoAPI menyimpan benih acak perantara dengan setiap pengguna. Untuk membentuk seed untuk generator nomor acak, aplikasi panggilan menyediakan bit yang mungkin dimilikinya—misalnya, input waktu mouse atau keyboard—yang kemudian dikombinasikan dengan benih tersimpan dan berbagai data sistem dan data pengguna seperti ID proses dan ID utas, jam sistem, waktu sistem, penghitung sistem, status memori, kluster disk gratis, blok lingkungan pengguna yang di-hash. Hasil ini digunakan untuk menyemai generator angka pseudorandom (PRNG). Di Windows Vista dengan Paket Layanan 1 (SP1) dan yang lebih baru, implementasi PRNG berbasis mode penghitung AES yang ditentukan dalam Publikasi Khusus NIST 800-90 digunakan. Di Windows Vista, Windows Storage Server 2003, dan Windows XP, PRNG yang ditentukan dalam Federal Information Processing Standard (FIPS) 186-2 digunakan. Jika aplikasi memiliki akses ke sumber acak yang baik, aplikasi dapat mengisi buffer pbBuffer dengan beberapa data acak sebelum memanggil CryptGenRandom. CSP kemudian menggunakan data ini untuk mengacak benih internalnya lebih lanjut. Dapat diterima untuk menghilangkan langkah inisialisasi buffer pbBuffer sebelum memanggil CryptGenRandom.

Contoh

Contoh berikut menunjukkan pembuatan 8 byte acak. Ini dapat digunakan untuk membuat kunci kriptografi atau untuk aplikasi apa pun yang menggunakan angka acak. Untuk contoh yang menyertakan konteks lengkap untuk contoh ini, lihat Contoh Program C: Menduplikasi Kunci Sesi.

//--------------------------------------------------------------------
// 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);
}

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincrypt.h
Pustaka	Advapi32.lib
DLL	Advapi32.dll

Lihat juga

CryptAcquireContext

CryptGenKey

CryptSetKeyParam

Pembuatan Kunci dan Fungsi Exchange

Bagikan melalui