Fungsi BCryptGenerateSymmetricKey (bcrypt.h)

Artikel
02/23/2024

Fungsi BCryptGenerateSymmetricKey membuat objek kunci untuk digunakan dengan algoritma enkripsi kunci simetris dari kunci yang disediakan.

Sintaks

NTSTATUS BCryptGenerateSymmetricKey(
  [in, out]       BCRYPT_ALG_HANDLE hAlgorithm,
  [out]           BCRYPT_KEY_HANDLE *phKey,
  [out, optional] PUCHAR            pbKeyObject,
  [in]            ULONG             cbKeyObject,
  [in]            PUCHAR            pbSecret,
  [in]            ULONG             cbSecret,
  [in]            ULONG             dwFlags
);

Parameter

[in, out] hAlgorithm

Handel penyedia algoritma yang dibuat dengan fungsi BCryptOpenAlgorithmProvider . Algoritma yang ditentukan ketika penyedia dibuat harus mendukung enkripsi kunci simetris.

[out] phKey

Penunjuk ke BCRYPT_KEY_HANDLE yang menerima handel kunci. Handel ini digunakan dalam fungsi berikutnya yang memerlukan kunci, seperti BCryptEncrypt. Handel ini harus dirilis ketika tidak lagi diperlukan dengan meneruskannya ke fungsi BCryptDestroyKey .

[out, optional] pbKeyObject

Penunjuk ke buffer yang menerima objek kunci. Parameter cbKeyObject berisi ukuran buffer ini. Ukuran buffer yang diperlukan dapat diperoleh dengan memanggil fungsi BCryptGetProperty untuk mendapatkan properti BCRYPT_OBJECT_LENGTH . Ini akan memberikan ukuran objek kunci untuk algoritma yang ditentukan.

Memori ini hanya dapat dikosongkan setelah handel kunci phKey dihancurkan.

Jika nilai parameter ini adalah NULL dan nilai parameter cbKeyObject adalah nol, memori untuk objek kunci dialokasikan dan dikosongkan oleh fungsi ini. Windows 7: Fungsionalitas manajemen memori ini tersedia dimulai dengan Windows 7.

[in] cbKeyObject

Ukuran, dalam byte, dari buffer pbKeyObject .

Jika nilai parameter ini nol dan nilai parameter pbKeyObject adalah NULL, memori untuk objek kunci dialokasikan dan dikosongkan oleh fungsi ini. Windows 7: Fungsionalitas manajemen memori ini tersedia dimulai dengan Windows 7.

[in] pbSecret

Penunjuk ke buffer yang berisi kunci untuk membuat objek kunci. Parameter cbSecret berisi ukuran buffer ini. Ini biasanya hash kata sandi atau beberapa data lain yang dapat direproduksi. Jika data yang diteruskan melebihi ukuran kunci target, data akan dipotong dan kelebihannya akan diabaikan.

Catatan Kami sangat menyarankan agar aplikasi meneruskan jumlah byte yang tepat yang diperlukan oleh kunci target.

[in] cbSecret

Ukuran, dalam byte, dari penyangga pbSecret .

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Tidak ada bendera yang saat ini ditentukan, jadi parameter ini harus nol.

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_BUFFER_TOO_SMALL	Ukuran objek kunci yang ditentukan oleh parameter cbKeyObject tidak cukup besar untuk menahan objek kunci.
STATUS_INVALID_HANDLE	Handel algoritma dalam parameter hAlgorithm tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.

Keterangan

Bergantung pada mode prosesor apa yang didukung penyedia, BCryptGenerateSymmetricKey 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 BCryptGenerateSymmetricKey harus mengacu pada memori yang tidak di-patahkan (atau dikunci).

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
DLL	Bcrypt.dll

Lihat juga

BCryptDestroyKey