Fungsi EncryptMessage (Schannel)
Fungsi EncryptMessage (Schannel) mengenkripsi pesan untuk memberikan privasi. EncryptMessage (Schannel) memungkinkan aplikasi untuk memilih di antara algoritma kriptografi yang didukung oleh mekanisme yang dipilih. Fungsi EncryptMessage (Schannel) menggunakan konteks keamanan yang direferensikan oleh handel konteks. Beberapa paket tidak memiliki pesan untuk dienkripsi atau didekripsi, melainkan memberikan hash integritas yang dapat diperiksa.
Saat menggunakan Schannel SSP, fungsi ini mengenkripsi pesan dengan menggunakan kunci sesi yang dinegosiasikan dengan pihak jarak jauh yang akan menerima pesan. Algoritma enkripsi ditentukan oleh [cipher suite](cipher-suites-in-schannel.md) yang digunakan.
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 EncryptMessage(
_In_ PCtxtHandle phContext,
_In_ ULONG fQOP,
_Inout_ PSecBufferDesc pMessage,
_In_ ULONG MessageSeqNo
);
Parameter
phContext [in]
Handel ke konteks keamanan yang akan digunakan untuk mengenkripsi pesan.
fQOP [in]
Bendera khusus paket yang menunjukkan kualitas perlindungan. Paket keamanan dapat menggunakan parameter ini untuk mengaktifkan pemilihan algoritma kriptografi.
Parameter ini bisa menjadi bendera berikut.
Nilai | Makna |
---|---|
|
Kirim pesan pemberitahuan Schannel. Dalam hal ini, parameter pMessage harus berisi kode peristiwa SSL/TLS dua byte standar. Nilai ini hanya didukung oleh Schannel SSP. Misalnya, dimulai dengan Windows Vista, pesan "server hello" yang dikirim oleh server selama protokol autentikasi ulang harus dienkripsi sebagai pemberitahuan TLS. |
pMessage [masuk, keluar]
Penunjuk ke struktur SecBufferDesc . Pada input, struktur mereferensikan satu atau beberapa struktur SecBuffer . Salah satunya bisa berjenis SECBUFFER_DATA. Buffer tersebut berisi pesan yang akan dienkripsi. Pesan dienkripsi di tempat, menimpa konten asli struktur.
Fungsi ini tidak memproses buffer dengan atribut SECBUFFER_READONLY.
Panjang struktur SecBuffer yang berisi pesan tidak boleh lebih besar dari cbMaximumMessage, yang diperoleh dari fungsi QueryContextAttributes (Schannel) (SECPKG_ATTR_STREAM_SIZES).
MessageSeqNo [in]
Nomor urut yang ditetapkan aplikasi transportasi ke pesan. Jika aplikasi transportasi tidak mempertahankan nomor urut, parameter ini harus nol.
Saat menggunakan Schannel SSP, parameter ini harus diatur ke nol. Schannel SSP tidak menggunakan nomor urut.
Nilai kembali
Jika fungsi berhasil, fungsi akan mengembalikan SEC_E_OK.
Jika fungsi gagal, fungsi mengembalikan salah satu kode kesalahan berikut.
Menampilkan kode | Deskripsi |
---|---|
|
Buffer output terlalu kecil. Untuk informasi selengkapnya, lihat Keterangan. |
|
Aplikasi ini mereferensikan konteks yang telah ditutup. Aplikasi yang ditulis dengan benar seharusnya tidak menerima kesalahan ini. |
|
Cipher yang dipilih untuk konteks keamanan tidak didukung. |
|
Tidak tersedia cukup memori untuk menyelesaikan tindakan yang diminta. |
|
Handel konteks yang tidak valid ditentukan dalam parameter phContext . |
|
Tidak ada buffer tipe SECBUFFER_DATA yang ditemukan. |
|
Kerahasiaan maupun integritas tidak didukung oleh konteks keamanan. |
Keterangan
Fungsi EncryptMessage (Schannel) mengenkripsi pesan berdasarkan pesan dan kunci sesi dari konteks keamanan.
Jika aplikasi transportasi membuat konteks keamanan untuk mendukung deteksi urutan dan pemanggil menyediakan nomor urut, fungsi menyertakan informasi ini dengan pesan terenkripsi. Termasuk informasi ini melindungi dari pemutaran ulang, penyisipan, dan penekanan pesan. Paket keamanan menggabungkan nomor urut yang diturunkan dari aplikasi transportasi.
Ketika digunakan dengan Schannel SSP, parameter pMessage harus berisi struktur SecBufferDesc dengan buffer berikut.
Catatan
Buffer ini harus disediakan dalam urutan yang ditampilkan.
Jenis buffer | Deskripsi |
---|---|
SECBUFFER_STREAM_HEADER | Digunakan secara internal. Tidak diperlukan inisialisasi. |
SECBUFFER_DATA | Berisi pesan teks biasa yang akan dienkripsi. |
SECBUFFER_STREAM_TRAILER | Digunakan secara internal. Tidak diperlukan inisialisasi. |
SECBUFFER_EMPTY | Digunakan secara internal. Tidak diperlukan inisialisasi. Ukurannya bisa nol. |
Saat Anda menggunakan Schannel SSP, tentukan ukuran maksimum setiap buffer dengan memanggil fungsi QueryContextAttributes (Schannel) dan menentukan atribut SECPKG_ATTR_STREAM_SIZES. Fungsi ini mengembalikan struktur SecPkgContext_StreamSizes yang anggotanya berisi ukuran maksimum untuk header (anggota cbHeader ), pesan (anggota cbMaximumMessage ) dan buffer trailer (anggota cbTrailer ).
Untuk performa optimal, struktur pMessage harus dialokasikan dari memori yang berdekatan.
Windows XP/2000: Fungsi ini juga dikenal sebagai SealMessage. Aplikasi sekarang harus menggunakan EncryptMessage (Schannel) saja.
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 |