Fungsi BCryptEncrypt (bcrypt.h)

Artikel
03/14/2023

Fungsi BCryptEncrypt mengenkripsi blok data.

Sintaks

NTSTATUS BCryptEncrypt(
  [in, out]           BCRYPT_KEY_HANDLE hKey,
  [in]                PUCHAR            pbInput,
  [in]                ULONG             cbInput,
  [in, optional]      VOID              *pPaddingInfo,
  [in, out, optional] PUCHAR            pbIV,
  [in]                ULONG             cbIV,
  [out, optional]     PUCHAR            pbOutput,
  [in]                ULONG             cbOutput,
  [out]               ULONG             *pcbResult,
  [in]                ULONG             dwFlags
);

Parameter

[in, out] hKey

Handel kunci yang digunakan untuk mengenkripsi data. Handel ini diperoleh dari salah satu fungsi pembuatan kunci, seperti BCryptGenerateSymmetricKey, BCryptGenerateKeyPair, atau BCryptImportKey.

[in] pbInput

Alamat buffer yang berisi teks biasa yang akan dienkripsi. Parameter cbInput berisi ukuran teks biasa untuk dienkripsi. Untuk informasi selengkapnya, lihat Keterangan.

[in] cbInput

Jumlah byte dalam buffer pbInput untuk dienkripsi.

[in, optional] pPaddingInfo

Penunjuk ke struktur yang berisi informasi padding. Parameter ini hanya digunakan dengan kunci asimetris dan mode enkripsi terautentikasi. Jika mode enkripsi terautentikasi digunakan, parameter ini harus menunjuk ke struktur BCRYPT_AUTHENTICATED_CIPHER_MODE_INFO . Jika kunci asimetris digunakan, jenis struktur yang dituju parameter ini ditentukan oleh nilai parameter dwFlags . Jika tidak, parameter harus diatur ke NULL.

[in, out, optional] pbIV

Alamat buffer yang berisi vektor inisialisasi (IV) untuk digunakan selama enkripsi. Parameter cbIV berisi ukuran buffer ini. Fungsi ini akan mengubah isi buffer ini. Jika Anda perlu menggunakan kembali IV nanti, pastikan Anda membuat salinan buffer ini sebelum memanggil fungsi ini.

Parameter ini bersifat opsional dan dapat berupa NULL jika tidak ada IV yang digunakan.

Ukuran IV yang diperlukan dapat diperoleh dengan memanggil fungsi BCryptGetProperty untuk mendapatkan properti BCRYPT_BLOCK_LENGTH . Ini akan memberikan ukuran blok untuk algoritma, yang juga merupakan ukuran IV.

[in] cbIV

Ukuran, dalam byte, dari buffer pbIV .

[out, optional] pbOutput

Alamat buffer yang menerima ciphertext yang dihasilkan oleh fungsi ini. Parameter cbOutput berisi ukuran buffer ini. Untuk informasi selengkapnya, lihat Keterangan.

Jika parameter ini NULL, fungsi BCryptEncrypt menghitung ukuran yang diperlukan untuk ciphertext data yang diteruskan dalam parameter pbInput . Dalam hal ini, lokasi yang diarahkan oleh parameter pcbResult berisi ukuran ini, dan fungsi mengembalikan STATUS_SUCCESS. Parameter pPaddingInfo tidak dimodifikasi .

Jika nilai parameter pbOutput dan pbInput adalah NULL, kesalahan dikembalikan kecuali algoritma enkripsi terautentikasi sedang digunakan. Dalam kasus terakhir, panggilan diperlakukan sebagai panggilan enkripsi terautentikasi dengan data panjang nol, dan tag autentikasi dikembalikan dalam parameter pPaddingInfo .

[in] cbOutput

Ukuran, dalam byte, dari buffer pbOutput . Parameter ini diabaikan jika parameter pbOutput adalah NULL.

[out] pcbResult

Penunjuk ke variabel ULONG yang menerima jumlah byte yang disalin ke buffer pbOutput . Jika pbOutput adalah NULL, ini menerima ukuran, dalam byte, diperlukan untuk ciphertext.

[in] dwFlags

Sekumpulan bendera yang mengubah perilaku fungsi ini. Set bendera yang diizinkan tergantung pada jenis kunci yang ditentukan oleh parameter hKey .

Jika kuncinya adalah kunci simetris, ini bisa menjadi nol atau nilai berikut.

Nilai	Makna
BCRYPT_BLOCK_PADDING	Memungkinkan algoritma enkripsi untuk mengayuh data ke ukuran blok berikutnya. Jika bendera ini tidak ditentukan, ukuran teks biasa yang ditentukan dalam parameter cbInput harus kelipatan ukuran blok algoritma. Ukuran blok dapat diperoleh dengan memanggil fungsi BCryptGetProperty untuk mendapatkan properti BCRYPT_BLOCK_LENGTH untuk kunci. Ini akan memberikan ukuran blok untuk algoritma. Bendera ini tidak boleh digunakan dengan mode enkripsi terautentikasi (AES-CCM dan AES-GCM).

Nilai

Makna

BCRYPT_BLOCK_PADDING

Memungkinkan algoritma enkripsi untuk mengayuh data ke ukuran blok berikutnya. Jika bendera ini tidak ditentukan, ukuran teks biasa yang ditentukan dalam parameter cbInput harus kelipatan ukuran blok algoritma.

Ukuran blok dapat diperoleh dengan memanggil fungsi BCryptGetProperty untuk mendapatkan properti BCRYPT_BLOCK_LENGTH untuk kunci. Ini akan memberikan ukuran blok untuk algoritma.

Bendera ini tidak boleh digunakan dengan mode enkripsi terautentikasi (AES-CCM dan AES-GCM).

Jika kuncinya adalah kunci asimetris, ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
BCRYPT_PAD_NONE	Jangan gunakan padding apa pun. Parameter pPaddingInfo tidak digunakan. Ukuran teks biasa yang ditentukan dalam parameter cbInput harus kelipatan ukuran blok algoritma.
BCRYPT_PAD_OAEP	Gunakan skema Optimal Asymmetric Encryption Padding (OAEP). Parameter pPaddingInfo adalah penunjuk ke struktur BCRYPT_OAEP_PADDING_INFO .
BCRYPT_PAD_PKCS1	Data akan dilapisi dengan angka acak untuk membulatkan ukuran blok. Parameter pPaddingInfo tidak digunakan.

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 yang ditentukan oleh parameter cbOutput tidak cukup besar untuk menahan ciphertext.
STATUS_INVALID_BUFFER_SIZE	Parameter cbInput bukan kelipatan ukuran blok algoritma dan BCRYPT_BLOCK_PADDING atau bendera BCRYPT_PAD_NONE tidak ditentukan dalam parameter dwFlags .
STATUS_INVALID_HANDLE	Handel kunci dalam parameter hKey tidak valid.
STATUS_INVALID_PARAMETER	Satu atau beberapa parameter tidak valid.
STATUS_NOT_SUPPORTED	Algoritma tidak mendukung enkripsi.

Keterangan

Parameter pbInput dan pbOutput dapat sama. Dalam hal ini, fungsi ini akan melakukan enkripsi di tempat. Ada kemungkinan bahwa ukuran data terenkripsi akan lebih besar dari ukuran data yang tidak terenkripsi, sehingga buffer harus cukup besar untuk menyimpan data terenkripsi. Jika pbInput dan pbOutput tidak sama maka kedua buffer mungkin tidak tumpang tindih.

Bergantung pada mode prosesor apa yang didukung penyedia, BCryptEncrypt 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 hKey harus berasal dari handel algoritma yang dikembalikan oleh penyedia yang dibuka dengan bendera BCRYPT_PROV_DISPATCH , dan setiap pointer yang diteruskan ke fungsi BCryptEncrypt harus mengacu pada memori yang tidak di-patah (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

BCryptDecrypt