Fungsi CryptDecrypt (wincrypt.h)

Artikel
07/16/2024

Important 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 CryptDecrypt mendekripsi data yang sebelumnya dienkripsi dengan menggunakan fungsi CryptEncrypt.

Perubahan penting untuk mendukung interoperabilitas email Ekstensi Surat Internet Aman/Multiguna (S/MIME) telah dilakukan ke CryptoAPI yang memengaruhi penanganan pesan yang diselimuti. Untuk informasi selengkapnya, lihat bagian Keterangan CryptMsgOpenToEncode.

Sintaksis

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

Parameter

[in] hKey

Handel ke kunci yang akan digunakan untuk dekripsi. Aplikasi mendapatkan handel ini dengan menggunakan fungsi CryptGenKey atau CryptImportKey.

Kunci ini menentukan algoritma dekripsi yang akan digunakan.

[in] hHash

Handel ke objek hash . Jika data akan didekripsi dan di-hash secara bersamaan, handel ke objek hash diteruskan dalam parameter ini. Nilai hash diperbarui dengan plaintext yang didekripsi. Opsi ini berguna saat mendekripsi dan memverifikasi tanda tangan secara bersamaan.

Sebelum memanggil CryptDecrypt, aplikasi harus mendapatkan handel ke objek hash dengan memanggil fungsi CryptCreateHash. Setelah dekripsi selesai, nilai hash dapat diperoleh dengan menggunakan fungsi CryptGetHashParam, juga dapat ditandatangani dengan menggunakan fungsi CryptSignHash, atau dapat digunakan untuk memverifikasi tanda tangan digital dengan menggunakan fungsi CryptVerifySignature.

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

[in] Final

Nilai Boolean yang menentukan apakah ini adalah bagian terakhir dalam seri yang didekripsi. Nilai ini TRUE jika ini adalah blok terakhir atau satu-satunya. Jika ini bukan blok terakhir, nilai ini FALSE. Untuk informasi selengkapnya, lihat Keterangan.

[in] dwFlags

Nilai bendera berikut ditentukan.

Nilai	Arti
CRYPT_OAEP 0x00000040	Gunakan Padding Enkripsi Asimetris Optimal (OAEP) (PKCS #1 versi 2). Bendera ini hanya didukung oleh Penyedia Kriptografi yang Ditingkatkan Microsoft dengan enkripsi/dekripsi RSA. Bendera ini tidak dapat digabungkan dengan bendera CRYPT_DECRYPT_RSA_NO_PADDING_CHECK.
CRYPT_DECRYPT_RSA_NO_PADDING_CHECK 0x00000020	Lakukan dekripsi pada BLOB tanpa memeriksa padding. Bendera ini hanya didukung oleh Penyedia Kriptografi yang Ditingkatkan Microsoft dengan enkripsi/dekripsi RSA. Bendera ini tidak dapat digabungkan dengan bendera CRYPT_OAEP.

[in, out] pbData

Penunjuk ke buffer yang berisi data yang akan didekripsi. Setelah dekripsi dilakukan, teks biasa ditempatkan kembali ke buffer yang sama ini.

Jumlah byte terenkripsi dalam buffer ini ditentukan oleh pdwDataLen.

[in, out] pdwDataLen

Penunjuk ke nilai DWORD yang menunjukkan panjang buffer pbData . Sebelum memanggil fungsi ini, aplikasi panggilan mengatur nilai DWORD ke jumlah byte yang akan didekripsi. Setelah dikembalikan, nilai DWORD berisi jumlah byte teks biasa yang didekripsi.

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

Mengembalikan nilai

Jika fungsi berhasil, fungsi mengembalikan nonzero (TRUE).

Jika fungsi gagal, fungsi akan mengembalikan nol (FALSE). Untuk informasi kesalahan yang diperluas, panggil 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 sesi hKey menentukan algoritma yang tidak didukung CSP ini.
NTE_BAD_DATA	Data yang akan didekripsi tidak valid. Misalnya, ketika cipher blok digunakan dan bendera Final FALSE, nilai yang ditentukan oleh pdwDataLen harus kelipatan ukuran blok. Kesalahan ini juga dapat dikembalikan ketika padding ditemukan tidak valid.
NTE_BAD_FLAGS	Parameter dwFlags nonzero.
NTE_BAD_HASH	Parameter hHash berisi handel yang tidak valid.
NTE_BAD_KEY	Parameter hKey tidak berisi handel yang valid ke kunci.
NTE_BAD_LEN	Ukuran buffer output terlalu kecil untuk menahan teks biasa yang dihasilkan.
NTE_BAD_UID	Konteks CSP yang ditentukan ketika kunci dibuat tidak dapat ditemukan.
NTE_DOUBLE_ENCRYPT	Aplikasi mencoba mendekripsi data yang sama dua kali.
NTE_FAIL	Fungsi gagal dengan cara yang tidak terduga.

Komentar

Jika sejumlah besar data harus didekripsi, data dapat dilakukan di bagian dengan memanggil CryptDecrypt berulang kali. Parameter Final harus diatur ke TRUE hanya pada panggilan terakhir keCryptDecrypt , sehingga mesin dekripsi dapat menyelesaikan proses dekripsi dengan benar. Tindakan tambahan berikut dilakukan saat FinalTRUE:

Jika kunci adalah kunci cipher blok, data diisi ke kelipatan ukuran blok cipher. Untuk menemukan ukuran blok cipher, gunakan CryptGetKeyParam untuk mendapatkan nilai KP_BLOCKLEN kunci.
Jika sandi beroperasi dalam mode penautan , operasi CryptDecrypt berikutnya mengatur ulang daftar umpan balik cipher ke nilai KP_IV kunci.
Jika cipher adalah cipher streaming , panggilan CryptDecrypt berikutnya mengatur ulang cipher ke status awal .

Tidak ada cara untuk mengatur daftar umpan balik cipher ke nilai KP_IV kunci tanpa mengatur parameter Akhir 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 CryptDecrypt. Hal 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 daftar 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)

    // Decrypt the block with the duplicate key.
    CryptDecrypt(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 ciphertext data yang akan didekripsi harus panjangnya sama dengan modulus kunci RSA yang digunakan untuk mendekripsi data. Jika ciphertext memiliki nol dalam byte yang paling signifikan, byte ini harus disertakan dalam buffer data input dan dalam panjang buffer input. Ciphertext harus dalam format little-endian .

Contoh

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

Persyaratan

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