Fungsi CryptGenKey (wincrypt.h)
Aplikasi panggilan harus menentukan algoritma saat memanggil fungsi ini. Karena jenis algoritma ini terus dibundel dengan kunci, aplikasi tidak perlu menentukan algoritma nanti ketika operasi kriptografi aktual dilakukan.
Sintaks
BOOL CryptGenKey(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
Parameter
[in] hProv
Handel ke penyedia layanan kriptografi (CSP) yang dibuat oleh panggilan ke CryptAcquireContext.
[in] Algid
Nilai ALG_ID yang mengidentifikasi algoritma yang kuncinya akan dihasilkan. Nilai untuk parameter ini bervariasi tergantung pada CSP yang digunakan.
Untuk nilai ALG_ID digunakan dengan Penyedia Kriptografi Dasar Microsoft, lihat Algoritma Penyedia Dasar.
Untuk nilai ALG_ID digunakan dengan Penyedia Kriptografi Microsoft Strong atau Penyedia Kriptografi yang Ditingkatkan Microsoft, lihat Algoritma Penyedia yang Ditingkatkan.
Untuk CSP Diffie-Hellman, gunakan salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Menentukan kunci Diffie-Hellman "Ephemeral". |
|
Menentukan kunci Diffie-Hellman "Simpan dan Teruskan". |
Selain menghasilkan kunci sesi untuk algoritma simetris, fungsi ini juga dapat menghasilkan pasangan kunci publik/privat. Setiap klien CryptoAPI umumnya memiliki dua pasangan kunci publik/privat. Untuk menghasilkan salah satu pasangan kunci ini, atur parameter Algid ke salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Pertukaran kunci |
|
Tanda Tangan Digital |
[in] dwFlags
Menentukan jenis kunci yang dihasilkan. Ukuran kunci sesi, kunci tanda tangan RSA, dan kunci pertukaran kunci RSA dapat diatur saat kunci dibuat. Ukuran kunci, yang mewakili panjang modulus kunci dalam bit, diatur dengan 16 bit atas parameter ini. Dengan demikian, jika kunci tanda tangan RSA 2.048-bit akan dihasilkan, nilai 0x08000000 dikombinasikan dengan nilai dwFlags lain yang telah ditentukan sebelumnya dengan operasi bitwise-OR. 16 bit atas 0x08000000 0x0800, atau desimal 2.048. Nilai RSA1024BIT_KEY dapat digunakan untuk menentukan kunci RSA 1024-bit.
Karena perubahan pembatasan kontrol ekspor, CSP default dan panjang kunci default dapat berubah di antara versi sistem operasi. Penting bahwa enkripsi dan dekripsi menggunakan CSP yang sama dan bahwa panjang kunci secara eksplisit diatur menggunakan parameter dwFlags untuk memastikan interoperabilitas pada platform sistem operasi yang berbeda.
Secara khusus, Penyedia Layanan Kriptografi Penuh RSA default adalah Penyedia Kriptografi Kuat Microsoft RSA. Penyedia Layanan Kriptografi Diffie-Hellman Tanda Tangan DSS default adalah Penyedia Kriptografi Diffie-Hellman Microsoft Enhanced DSS. Masing-masing CSP ini memiliki panjang kunci konten default 128-bit untuk RC2 dan RC4 dan panjang kunci default 1.024-bit untuk algoritma kunci publik.
Jika 16 bit atas adalah nol, ukuran kunci default dihasilkan. Jika kunci yang lebih besar dari maksimum atau lebih kecil dari minimum ditentukan, panggilan gagal dengan kode ERROR_INVALID_PARAMETER.
Tabel berikut mencantumkan tanda tangan minimum, default, dan maksimum serta panjang kunci pertukaran yang dimulai dengan Windows XP.
| Jenis kunci dan penyedia | Panjang minimum | Panjang default | Panjang maksimum |
|---|---|---|---|
|
Penyedia Dasar RSA Tanda Tangan dan ExchangeKeys |
384 | 512 | 16.384 |
|
Penyedia RSA yang Kuat dan Ditingkatkan Kunci Tanda Tangan dan Exchange |
384 | 1\.024 | 16.384 |
|
Penyedia Dasar DSS Kunci Tanda Tangan |
512 | 1\.024 | 1\.024 |
|
Penyedia Dasar DSS Kunci Exchange |
Tidak berlaku | Tidak berlaku | Tidak berlaku |
|
Penyedia Dasar DSS/DH Kunci Tanda Tangan |
512 | 1\.024 | 1\.024 |
|
Penyedia Dasar DSS/DH Kunci Exchange |
512 | 512 | 1\.024 |
|
Penyedia DSS/DH yang Ditingkatkan Kunci Tanda Tangan |
512 | 1\.024 | 1\.024 |
|
Penyedia DSS/DH yang Ditingkatkan Kunci Exchange |
512 | 1\.024 | 4,096 |
Untuk panjang kunci sesi, lihat CryptDeriveKey.
Untuk informasi selengkapnya tentang kunci yang dihasilkan menggunakan penyedia Microsoft, lihat Penyedia Layanan Kriptografi Microsoft.
16-bit yang lebih rendah dari parameter ini bisa nol atau kombinasi dari satu atau beberapa nilai berikut.
| Nilai | Makna |
|---|---|
|
Jika bendera ini diatur, kunci dapat diekspor sampai handelnya ditutup oleh panggilan ke CryptDestroyKey. Ini memungkinkan kunci yang baru dibuat untuk diekspor setelah pembuatan untuk pengarsipan atau pemulihan kunci. Setelah handel ditutup, kunci tidak lagi dapat diekspor. |
|
Bendera ini tidak digunakan. |
|
Jika bendera ini diatur, maka kunci diberi nilai garam acak secara otomatis. Anda dapat mengambil nilai garam ini dengan menggunakan fungsi CryptGetKeyParam dengan parameter dwParam diatur ke KP_SALT.
Jika bendera ini tidak diatur, maka kunci diberi nilai garam nol. Ketika kunci dengan nilai garam nonzero diekspor (melalui CryptExportKey), maka nilai garam juga harus diperoleh dan disimpan dengan BLOB kunci. |
|
Bendera ini tidak digunakan. |
|
Jika bendera ini diatur, maka kunci dapat ditransfer keluar dari CSP ke blob kunci dengan menggunakan fungsi CryptExportKey . Karena kunci sesi umumnya harus dapat diekspor, bendera ini biasanya harus diatur saat dibuat.
Jika bendera ini tidak diatur, maka kunci tidak dapat diekspor. Untuk kunci sesi, ini berarti bahwa kunci hanya tersedia dalam sesi saat ini dan hanya aplikasi yang membuatnya yang dapat menggunakannya. Untuk pasangan kunci publik/privat, ini berarti bahwa kunci privat tidak dapat diangkut atau dicadangkan. Bendera ini hanya berlaku untuk kunci sesi dan BLOB kunci privat. Ini tidak berlaku untuk kunci publik, yang selalu dapat diekspor. |
|
Bendera ini menentukan perlindungan kunci yang kuat. Ketika bendera ini diatur, pengguna diminta untuk memasukkan kata sandi untuk kunci saat kunci dibuat. Pengguna akan diminta untuk memasukkan kata sandi setiap kali kunci ini digunakan.
Bendera ini hanya digunakan oleh CSP yang disediakan oleh Microsoft. CSP pihak ketiga akan menentukan perilaku mereka sendiri untuk perlindungan kunci yang kuat. Menentukan bendera ini menyebabkan hasil yang sama dengan memanggil fungsi ini dengan bendera CRYPT_USER_PROTECTED ketika perlindungan kunci yang kuat ditentukan dalam registri sistem. Jika bendera ini ditentukan dan handel penyedia dalam parameter hProv dibuat dengan menggunakan bendera CRYPT_VERIFYCONTEXT atau CRYPT_SILENT , fungsi ini akan mengatur kesalahan terakhir ke NTE_SILENT_CONTEXT dan mengembalikan nol. Windows Server 2003 dan Windows XP: Bendera ini tidak didukung. |
|
Bendera ini tidak digunakan. |
|
Bendera ini tidak digunakan. |
|
Bendera ini menentukan bahwa nilai tanpa garam dialokasikan untuk kunci simetris empat puluh bit. Untuk informasi selengkapnya, lihat Fungsionalitas Nilai Garam. |
|
Bendera ini tidak digunakan. |
|
Bendera ini menentukan pembuatan kunci awal Diffie-Hellman atau DSS. Bendera ini hanya berguna dengan CSP Diffie-Hellman dan DSS. Saat digunakan, panjang kunci default akan digunakan kecuali panjang kunci ditentukan dalam 16 bit atas parameter dwFlags . Jika parameter yang melibatkan panjang kunci diatur pada kunci PREGEN Diffie-Hellman atau DSS menggunakan CryptSetKeyParam, panjang kunci harus kompatibel dengan panjang kunci yang ditetapkan di sini. |
|
Bendera ini tidak digunakan. |
|
Bendera ini tidak digunakan. |
|
Bendera ini tidak digunakan. |
|
Jika bendera ini diatur, pengguna akan diberi tahu melalui kotak dialog atau metode lain saat tindakan tertentu mencoba menggunakan kunci ini. Perilaku yang tepat ditentukan oleh CSP yang digunakan. Jika konteks penyedia dibuka dengan set bendera CRYPT_SILENT, menggunakan bendera ini menyebabkan kegagalan dan kesalahan terakhir diatur ke NTE_SILENT_CONTEXT. |
|
Bendera ini tidak digunakan. |
[out] phKey
Alamat tempat fungsi menyalin handel kunci yang baru dibuat. Setelah Anda selesai menggunakan kunci, hapus handel ke kunci dengan memanggil fungsi CryptDestroyKey .
Mengembalikan nilai
Mengembalikan bukan nol jika berhasil atau nol sebaliknya.
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 |
|---|---|
|
Salah satu parameter menentukan handel yang tidak valid. |
|
Salah satu parameter berisi nilai yang tidak valid. Ini paling sering merupakan pointer yang tidak valid. |
|
Parameter Algid menentukan algoritma yang tidak didukung CSP ini. |
|
Parameter dwFlags berisi nilai yang tidak valid. |
|
Parameter hProv tidak berisi handel konteks yang valid. |
|
Fungsi gagal dengan cara yang tidak terduga. |
|
Penyedia tidak dapat melakukan tindakan karena konteks diperoleh sebagai senyap. |
Keterangan
Jika kunci dihasilkan untuk cipher bloksimetris, kunci, secara default, diatur dalam mode rantai blok cipher (CBC) dengan vektor inisialisasi nol. Mode cipher ini menyediakan metode default yang baik untuk mengenkripsi data secara massal. Untuk mengubah parameter ini, gunakan fungsi CryptSetKeyParam .
Untuk memilih panjang kunci yang sesuai, metode berikut disarankan:
- Hitung algoritma yang didukung CSP dan dapatkan panjang kunci maksimum dan minimum untuk setiap algoritma. Untuk melakukan ini, panggil CryptGetProvParam dengan PP_ENUMALGS_EX.
- Gunakan panjang minimum dan maksimum untuk memilih panjang kunci yang sesuai. Tidak selalu disarankan untuk memilih panjang maksimum karena ini dapat menyebabkan masalah performa.
- Setelah panjang kunci yang diinginkan dipilih, gunakan 16 bit atas parameter dwFlags untuk menentukan panjang kunci.
Contoh
Contoh berikut menunjukkan pembuatan kunci sesi acak. Untuk contoh yang menyertakan konteks lengkap untuk contoh ini, lihat Contoh Program C: Mengenkripsi File. Untuk contoh lain yang menggunakan fungsi ini, lihat Contoh Program C: Mendekripsi File.
//-------------------------------------------------------------------
// Declare the handle to the key.
HCRYPTKEY hKey;
//-------------------------------------------------------------------
// This example assumes that a cryptographic context
// has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
// Create a random session key.
if(CryptGenKey(
hCryptProv,
ENCRYPT_ALGORITHM,
KEYLENGTH | CRYPT_EXPORTABLE,
&hKey))
{
printf("A session key has been created.\n");
}
else
{
printf("Error during CryptGenKey.\n");
exit(1);
}
//-------------------------------------------------------------------
// The key created can be exported into a key BLOB that can be
// written to a file.
// ...
// When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
printf("Error during CryptDestroyKey.\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
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk