Fungsi CryptEncrypt (wincrypt.h)

Artikel
03/15/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 CryptEncrypt mengenkripsi data. Algoritma yang digunakan untuk mengenkripsi data ditunjuk oleh kunci yang dipegang oleh modul CSP dan dirujuk oleh parameter hKey .

Perubahan penting untuk mendukung interoperabilitas email Secure/Multipurpose Internet Mail Extensions (S/MIME) telah dilakukan ke CryptoAPI yang memengaruhi penanganan pesan yang diselimuti. Untuk informasi selengkapnya, lihat bagian Keterangan dari CryptMsgOpenToEncode.

Penting Fungsi CryptEncrypt tidak dijamin aman untuk utas dan dapat mengembalikan hasil yang salah jika dipanggil secara bersamaan oleh beberapa penelepon.

Sintaks

BOOL CryptEncrypt(
  [in]      HCRYPTKEY  hKey,
  [in]      HCRYPTHASH hHash,
  [in]      BOOL       Final,
  [in]      DWORD      dwFlags,
  [in, out] BYTE       *pbData,
  [in, out] DWORD      *pdwDataLen,
  [in]      DWORD      dwBufLen
);

Parameter

[in] hKey

Handel ke kunci enkripsi. Aplikasi mendapatkan handel ini dengan menggunakan CryptGenKey atau fungsi CryptImportKey .

Kunci menentukan algoritma enkripsi yang digunakan.

[in] hHash

Handel ke objek hash. Jika data akan di-hash dan dienkripsi secara bersamaan, handel ke objek hash dapat diteruskan dalam parameter hHash . Nilai hash diperbarui dengan teks biasa yang diteruskan. Opsi ini berguna saat menghasilkan teks yang ditandatangani dan dienkripsi.

Sebelum memanggil CryptEncrypt, aplikasi harus mendapatkan handel ke objek hash dengan memanggil fungsi CryptCreateHash . Setelah enkripsi selesai, nilai hash dapat diperoleh dengan menggunakan fungsi CryptGetHashParam , atau hash dapat ditandatangani dengan menggunakan fungsi CryptSignHash .

Jika tidak ada hash yang harus dilakukan, parameter ini harus NULL.

[in] Final

Nilai Boolean yang menentukan apakah ini bagian terakhir dalam seri yang sedang dienkripsi. Final diatur ke TRUE untuk blok terakhir atau hanya dan ke FALSE jika ada lebih banyak blok yang akan dienkripsi. Untuk informasi selengkapnya, lihat Keterangan.

[in] dwFlags

Nilai dwFlags berikut didefinisikan tetapi dicadangkan untuk digunakan di masa mendatang.

Nilai	Makna
CRYPT_OAEP	Gunakan Padding Enkripsi Asimetris Optimal (OAEP) (PKCS #1 versi 2). Bendera ini hanya didukung oleh Penyedia Kriptografi yang Ditingkatkan Microsoft dengan enkripsi/dekripsi RSA.

[in, out] pbData

Penunjuk ke buffer yang berisi teks biasa yang akan dienkripsi. Teks biasa dalam buffer ini ditimpa dengan ciphertext yang dibuat oleh fungsi ini.

Parameter pdwDataLen menunjuk ke variabel yang berisi panjang, dalam byte, dari teks biasa. Parameter dwBufLen berisi ukuran total, dalam byte, dari buffer ini.

Jika parameter ini berisi NULL, fungsi ini akan menghitung ukuran yang diperlukan untuk ciphertext dan menempatkannya dalam nilai yang ditunjukkan oleh parameter pdwDataLen .

[in, out] pdwDataLen

Penunjuk ke nilai DWORD yang , pada entri, berisi panjang, dalam byte, teks biasa dalam buffer pbData . Saat keluar, DWORD ini berisi panjang, dalam byte, dari ciphertext yang ditulis ke buffer pbData .

Jika buffer yang dialokasikan untuk pbData tidak cukup besar untuk menyimpan data terenkripsi, GetLastError mengembalikan ERROR_MORE_DATA dan menyimpan ukuran buffer yang diperlukan, dalam byte, dalam nilai DWORD yang ditunjukkan oleh pdwDataLen.

Jika pbDataADALAH NULL, tidak ada kesalahan yang dikembalikan, dan fungsi menyimpan ukuran data terenkripsi, dalam byte, dalam nilai DWORD yang diarahkan oleh pdwDataLen. Ini memungkinkan aplikasi untuk menentukan ukuran buffer yang benar.

Ketika cipher blok digunakan, panjang data ini harus berupa kelipatan ukuran blok kecuali ini adalah bagian akhir data yang akan dienkripsi dan parameter Akhir adalah TRUE.

[in] dwBufLen

Menentukan ukuran total, dalam byte, dari buffer pbData input.

Perhatikan bahwa, tergantung pada algoritma yang digunakan, teks terenkripsi dapat lebih besar dari teks biasa asli. Dalam hal ini, buffer pbData harus cukup besar untuk berisi teks terenkripsi dan padding apa pun.

Sebagai aturan, jika cipher aliran digunakan, ciphertext berukuran sama dengan teks biasa. Jika cipher blok digunakan, ciphertext hingga panjang blok lebih besar dari teks biasa.

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan bukan nol (TRUE).

Jika fungsi gagal, fungsi akan mengembalikan 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 mengikuti.

Nilai	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_ALGID	Kunci sesihKey menentukan algoritma yang tidak didukung CSP ini.
NTE_BAD_DATA	Data yang akan dienkripsi tidak valid. Misalnya, ketika cipher blok digunakan dan bendera AkhirFALSE, nilai yang ditentukan oleh pdwDataLen harus kelipatan ukuran blok.
NTE_BAD_FLAGS	Parameter dwFlags bukan nol.
NTE_BAD_HASH	Parameter hHash berisi handel yang tidak valid.
NTE_BAD_HASH_STATE	Upaya dilakukan untuk menambahkan data ke objek hash yang sudah ditandai "selesai."
NTE_BAD_KEY	Parameter hKey tidak berisi handel yang valid ke kunci.
NTE_BAD_LEN	Ukuran buffer output terlalu kecil untuk menahan ciphertext yang dihasilkan.
NTE_BAD_UID	Konteks CSP yang ditentukan ketika kunci dibuat tidak dapat ditemukan.
NTE_DOUBLE_ENCRYPT	Aplikasi mencoba mengenkripsi data yang sama dua kali.
NTE_FAIL	Fungsi gagal dengan cara yang tidak terduga.
NTE_NO_MEMORY	CSP kehabisan memori selama operasi.

Keterangan

Jika sejumlah besar data akan dienkripsi, data dapat dilakukan di bagian dengan memanggil CryptEncrypt berulang kali. Parameter Akhir harus diatur ke TRUE pada panggilan terakhir ke CryptEncrypt, sehingga mesin enkripsi dapat menyelesaikan proses enkripsi dengan benar. Tindakan tambahan berikut dilakukan saat Finaltrue:

Jika kunci adalah kunci cipher blok, data diisi ke kelipatan ukuran blok cipher. Jika panjang data sama dengan ukuran blok cipher, satu blok tambahan padding ditambahkan ke data. Untuk menemukan ukuran blok cipher, gunakan CryptGetKeyParam untuk mendapatkan nilai KP_BLOCKLEN kunci.
Jika cipher beroperasi dalam mode penautan, operasi CryptEncrypt berikutnya mengatur ulang daftar umpan balik cipher ke nilai KP_IV kunci.
Jika cipher adalah cipher aliran, CryptEncrypt berikutnya mengatur ulang cipher ke status awalnya.

Tidak ada cara untuk mengatur register umpan balik cipher ke nilai KP_IV kunci tanpa mengatur parameter Final ke TRUE. Jika ini diperlukan, seperti dalam kasus di mana Anda tidak ingin menambahkan blok padding tambahan atau mengubah ukuran setiap blok, Anda dapat mensimulasikan ini dengan membuat duplikat kunci asli dengan menggunakan fungsi CryptDuplicateKey , dan meneruskan kunci duplikat ke fungsi CryptEncrypt . Ini menyebabkan KP_IV kunci asli ditempatkan di kunci duplikat. Setelah membuat atau mengimpor kunci asli, Anda tidak dapat menggunakan kunci asli untuk enkripsi karena register umpan balik kunci akan diubah. Pseudocode berikut menunjukkan bagaimana hal ini dapat dilakukan.

// Set the IV for the original key. Do not use the original key for 
// encryption or decryption after doing this because the key's 
// feedback register will get modified and you cannot change it.
CryptSetKeyParam(hOriginalKey, KP_IV, newIV)

while(block = NextBlock())
{
    // Create a duplicate of the original key. This causes the 
    // original key's IV to be copied into the duplicate key's 
    // feedback register.
    hDuplicateKey = CryptDuplicateKey(hOriginalKey)

    // Encrypt the block with the duplicate key.
    CryptEncrypt(hDuplicateKey, block)

    // Destroy the duplicate key. Its feedback register has been 
    // modified by the CryptEncrypt function, so it cannot be used
    // again. It will be re-duplicated in the next iteration of the 
    // loop.
    CryptDestroyKey(hDuplicateKey)
}

Penyedia Kriptografi yang Ditingkatkan Microsoft mendukung enkripsi langsung dengan kunci publik RSA dan dekripsi dengan kunci privat RSA. Enkripsi menggunakan PKCS #1 padding. Pada dekripsi, padding ini diverifikasi. Panjang data teks biasa yang dapat dienkripsi dengan panggilan ke CryptEncrypt dengan kunci RSA adalah panjang modulus kunci dikurangi sebelas byte. Sebelas byte adalah minimum yang dipilih untuk PKCS #1 padding. Ciphertext dikembalikan dalam format little-endian .

Contoh

Untuk contoh yang menggunakan fungsi ini, lihat Contoh Program C: Mengenkripsi File dan Contoh Program C: Mendekripsi File.

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