Fungsi DecryptMessage (Schannel)

Artikel
06/03/2023

Fungsi DecryptMessage (Schannel) mendekripsi pesan. Beberapa paket tidak mengenkripsi dan mendekripsi pesan melainkan melakukan dan memeriksa hash integritas.

Fungsi ini juga digunakan dengan penyedia dukungan keamanan (SSP) Schannel untuk memberi sinyal permintaan dari pengirim pesan untuk negosiasi ulang (pengulangan) atribut koneksi atau untuk mematikan koneksi.

Catatan

EncryptMessage (Schannel) dan DecryptMessage (Schannel) dapat dipanggil pada saat yang sama dari dua utas yang berbeda dalam konteks antarmuka penyedia dukungan keamanan tunggal (SSPI) jika satu utas mengenkripsi dan yang lainnya mendekripsi. Jika lebih dari satu utas mengenkripsi, atau lebih dari satu utas mendekripsi, setiap utas harus mendapatkan konteks unik.

Sintaks

SECURITY_STATUS SEC_Entry DecryptMessage(
  _In_    PCtxtHandle    phContext,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo,
  _Out_   PULONG         pfQOP
);

Parameter

phContext [in]

Handel ke konteks keamanan yang akan digunakan untuk mendekripsi pesan.

pMessage [masuk, keluar]

Penunjuk ke struktur SecBufferDesc . Pada input, struktur mereferensikan satu atau beberapa struktur SecBuffer . Salah satunya mungkin berjenis SECBUFFER_DATA. Buffer tersebut berisi pesan terenkripsi. Pesan terenkripsi didekripsi di tempatnya, menimpa konten asli buffernya.

Saat menggunakan Schannel SSP dengan konteks yang tidak berorientasi pada koneksi, pada input, struktur harus berisi empat struktur SecBuffer . Tepat satu buffer harus berjenis SECBUFFER_DATA dan berisi pesan terenkripsi, yang didekripsi di tempatnya. Buffer yang tersisa digunakan untuk output dan harus berjenis SECBUFFER_EMPTY. Untuk konteks berorientasi koneksi, buffer jenis SECBUFFER_DATA harus disediakan, seperti yang dicatat untuk konteks berorientasi nonkoneksi. Selain itu, buffer jenis SECBUFFER_TOKEN kedua yang berisi token keamanan juga harus disediakan.

MessageSeqNo [in]

Nomor urut yang diharapkan oleh aplikasi transportasi, jika ada. Jika aplikasi transportasi tidak mempertahankan nomor urut, parameter ini harus diatur ke nol.

Saat menggunakan Schannel SSP, parameter ini harus diatur ke nol. Schannel SSP tidak menggunakan nomor urut.

pfQOP [out]

Penunjuk ke variabel jenis ULONG yang menerima bendera khusus paket yang menunjukkan kualitas perlindungan.

Saat menggunakan Schannel SSP, parameter ini tidak digunakan dan harus diatur ke NULL.

Parameter ini bisa menjadi bendera berikut.

Nilai	Makna
SECQOP_WRAP_NO_ENCRYPT	Pesan tidak dienkripsi, tetapi header atau trailer diproduksi. Catatan: KERB_WRAP_NO_ENCRYPT memiliki nilai yang sama dan makna yang sama.

Nilai kembali

Jika fungsi memverifikasi bahwa pesan diterima dalam urutan yang benar, fungsi mengembalikan SEC_E_OK.

Jika fungsi gagal mendekripsi pesan, fungsi mengembalikan salah satu kode kesalahan berikut.

Menampilkan kode	Deskripsi
SEC_E_INVALID_HANDLE	Handel konteks yang tidak valid ditentukan dalam parameter phContext . Digunakan dengan Schannel SSP.
SEC_E_INVALID_TOKEN	Buffer memiliki jenis yang salah atau tidak ada buffer jenis SECBUFFER_DATA yang ditemukan. Digunakan dengan Schannel SSP.
SEC_E_MESSAGE_ALTERED	Pesan telah diubah. Digunakan dengan Schannel SSP.
SEC_E_OUT_OF_SEQUENCE	Pesan tidak diterima dalam urutan yang benar.
SEC_I_CONTEXT_EXPIRED	Pengirim pesan telah selesai menggunakan koneksi dan telah memulai pematian. Untuk informasi tentang memulai atau mengenali pematian, lihat Mematikan Koneksi Schannel. Digunakan dengan Schannel SSP.
SEC_I_RENEGOTIATE	Pihak jarak jauh memerlukan urutan jabat tangan baru atau aplikasi baru saja memulai pematian. Kembali ke perulangan negosiasi dan panggil AcceptSecurityContext (Schannel) atau InitializeSecurityContext (Schannel), teruskan SECBUFFER_EXTRA yang dikembalikan dari DecryptMessage().

Keterangan

Terkadang aplikasi akan membaca data dari pihak jarak jauh, mencoba mendekripsinya dengan menggunakan DecryptMessage (Schannel), dan menemukan bahwa DecryptMessage (Schannel) berhasil tetapi buffer output kosong. Ini adalah perilaku normal, dan aplikasi harus dapat menanganinya.

Saat Anda menggunakan Schannel SSP, fungsi DecryptMessage (Umum) mengembalikan SEC_I_CONTEXT_EXPIRED ketika pengirim pesan telah mematikan koneksi. Untuk informasi tentang memulai atau mengenali pematian, lihat Mematikan Koneksi Schannel.

Jika Anda menggunakan TLS 1.0, Anda mungkin perlu memanggil fungsi ini beberapa kali, menyesuaikan buffer input pada setiap panggilan, untuk mendekripsi seluruh pesan.

Fungsi DecryptMessage (Schannel) mengembalikan SEC_I_RENEGOTIATE ketika pesan protokol TLS pasca-jabat tangan selain data aplikasi diterima. Setelah fungsi DecryptMessage (Schannel) mengembalikan SEC_I_RENEGOTIATE, panggilan EncryptMessage() dan DecryptMessage() lebih lanjut akan gagal dengan SEC_E_CONTEXT_EXPIRED. Aplikasi menangani situasi ini dengan memanggil AcceptSecurityContext (Schannel) ( sisi server) atau InitializeSecurityContext (Schannel) ( sisi klien) dan meneruskan SECBUFFER_EXTRA dikembalikan dari DecryptMessage(). Setelah panggilan awal ini mengembalikan nilai, lanjutkan seolah-olah aplikasi Anda membuat koneksi baru. Kemudian aplikasi dapat terus memanggil EncryptMessage() dan DecryptMessage(). Untuk informasi selengkapnya, lihat Membuat Konteks Keamanan Schannel.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Header	Sspi.h (termasuk Security.h)
Pustaka	Secur32.lib
DLL	Secur32.dll

Bagikan melalui