Fungsi AcceptSecurityContext (Schannel)

Artikel
08/14/2024

Fungsi AcceptSecurityContext (Schannel) memungkinkan komponen server aplikasi transportasi untuk membangun konteks keamanan antara server dan klien jarak jauh. Klien jarak jauh menggunakan fungsi InitializeSecurityContext (Schannel) untuk memulai proses pembentukan konteks keamanan. Server dapat memerlukan satu atau beberapa token balasan dari klien jarak jauh untuk menyelesaikan pembentukan konteks keamanan.

Sintaks

SECURITY_STATUS SEC_Entry AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _Inout_opt_ PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          fContextReq,
  _In_        ULONG          TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsTimeStamp
);

Parameter

phCredential[in, optional]

Handel ke kredensial server. Server memanggil fungsi AcquireCredentialsHandle (Schannel) dengan bendera SECPKG_CRED_INBOUND atau SECPKG_CRED_BOTH diatur untuk mengambil handel ini.

phContext[in, out, optional]

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke AcceptSecurityContext (Schannel), pointer ini adalah NULL. Pada panggilan berikutnya, phContext adalah handel ke konteks yang terbentuk sebagian yang dikembalikan dalam parameter phNewContext oleh panggilan pertama.

Peringatan

Jangan gunakan handel konteks yang sama dalam panggilan bersamaan ke AcceptSecurityContext (Schannel). Implementasi API di penyedia layanan keamanan tidak aman untuk utas.

pInput[in, optional]

Penunjuk ke struktur SecBufferDesc yang dihasilkan oleh panggilan klien ke InitializeSecurityContext (Schannel) yang berisi deskriptor buffer input.

Saat menggunakan penyedia dukungan keamanan (SSP) Schannel, buffer pertama harus berjenis SECBUFFER_TOKEN dan berisi token keamanan yang diterima dari klien. Buffer kedua harus berjenis SECBUFFER_EMPTY.

fContextReq[in]

Bendera bit yang menentukan atribut yang diperlukan oleh server untuk menetapkan konteks. Bendera bit dapat digabungkan dengan menggunakan operasi bitwise-OR. Parameter ini bisa menjadi satu atau beberapa nilai berikut.

Nilai	Makna
ASC_REQ_ALLOCATE_MEMORY	Digest dan Schannel akan mengalokasikan buffer output untuk Anda. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer .
ASC_REQ_CONFIDENTIALITY	Mengenkripsi dan mendekripsi pesan. Digest SSP hanya mendukung bendera ini untuk SASL.
ASC_REQ_CONNECTION	Konteks keamanan tidak akan menangani pesan pemformatan.
ASC_REQ_EXTENDED_ERROR	Ketika terjadi kesalahan, pihak jarak jauh akan diberi tahu.
ASC_REQ_MUTUAL_AUTH	Klien diperlukan untuk menyediakan sertifikat yang akan digunakan untuk autentikasi klien.
ASC_REQ_REPLAY_DETECT	Mendeteksi paket yang diputar ulang.
ASC_REQ_SEQUENCE_DETECT	Mendeteksi pesan yang diterima secara tidak berurutan.
ASC_REQ_STREAM	Mendukung koneksi berorientasi aliran. Bendera ini hanya didukung oleh Schannel.

Untuk kemungkinan bendera atribut dan maknanya, lihat Persyaratan Konteks. Bendera yang digunakan untuk parameter ini diawali dengan ASC_REQ, misalnya, ASC_REQ_DELEGATE.

Atribut yang diminta mungkin tidak didukung oleh klien. Untuk informasi selengkapnya, lihat parameter pfContextAttr .

TargetDataRep[in]

Parameter ini tidak digunakan dengan Schannel. Tentukan nol untuk parameter ini.

phNewContext[in, out, optional]

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke AcceptSecurityContext (Schannel), pointer ini menerima handel konteks baru. Pada panggilan berikutnya, phNewContext dapat sama dengan handel yang ditentukan dalam parameter phContext . phNewContext tidak boleh NULL.

pOutput[in, out, optional]

Penunjuk ke struktur SecBufferDesc yang berisi deskriptor buffer output. Buffer ini dikirim ke klien untuk dimasukkan ke dalam panggilan tambahan ke InitializeSecurityContext (Schannel). Buffer output dapat dihasilkan meskipun fungsi mengembalikan SEC_E_OK. Setiap buffer yang dihasilkan harus dikirim kembali ke aplikasi klien.

Pada output, buffer ini menerima token untuk konteks keamanan. Token harus dikirim ke klien. Fungsi ini juga dapat mengembalikan buffer jenis SECBUFFER_EXTRA. Selain itu, penelepon harus meneruskan buffer jenis SECBUFFER_ALERT. Pada output, jika pemberitahuan dibuat, buffer ini berisi informasi tentang pemberitahuan tersebut, dan fungsi gagal.

pfContextAttr[out]

Penunjuk ke variabel yang menerima sekumpulan bendera bit yang menunjukkan atribut konteks yang ditetapkan. Untuk deskripsi berbagai atribut, lihat Persyaratan Konteks. Bendera yang digunakan untuk parameter ini diawali dengan ASC_RET, misalnya, ASC_RET_DELEGATE.

Jangan periksa atribut terkait keamanan hingga panggilan fungsi akhir berhasil dikembalikan. Bendera atribut yang tidak terkait dengan keamanan, seperti bendera ASC_RET_ALLOCATED_MEMORY, dapat diperiksa sebelum pengembalian akhir.

ptsTimeStamp[out, optional]

Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa konteks. Kami menyarankan agar paket keamanan selalu mengembalikan nilai ini di waktu setempat.

Ini opsional saat menggunakan Schannel SSP. Ketika pihak jarak jauh telah menyediakan sertifikat yang akan digunakan untuk autentikasi, parameter ini menerima waktu kedaluwarsa untuk sertifikat tersebut. Jika tidak ada sertifikat yang disediakan, nilai waktu maksimum dikembalikan.

Catatan

Hingga panggilan terakhir dari proses autentikasi, waktu kedaluwarsa untuk konteks dapat salah karena lebih banyak informasi akan diberikan selama tahap selanjutnya dari negosiasi. Oleh karena itu, ptsTimeStamp harus NULL sampai panggilan terakhir ke fungsi.

Mengembalikan nilai

Fungsi ini mengembalikan salah satu nilai berikut.

Mengembalikan kode/nilai	Deskripsi
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Fungsi berhasil. Data dalam buffer input tidak lengkap. Aplikasi harus membaca data tambahan dari klien dan memanggil [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) lagi. Ketika nilai ini dikembalikan, buffer pInput berisi struktur [SecBuffer](/windows/win32/api/sspi/ns-sspi-secbuffer) dengan anggota BufferTypeSECBUFFER_MISSING. Anggota cbBufferSecBuffer berisi nilai yang menunjukkan jumlah byte tambahan yang harus dibaca fungsi dari klien sebelum fungsi ini berhasil. Meskipun nomor ini tidak selalu akurat, menggunakannya dapat membantu performa dengan menghindari beberapa panggilan ke fungsi ini.
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	Fungsi gagal. Tidak tersedia cukup memori untuk menyelesaikan tindakan yang diminta.
SEC_E_INTERNAL_ERROR 0x80090304L	Fungsi gagal. Terjadi kesalahan yang tidak memetakan ke kode galat SSPI.
SEC_E_INVALID_HANDLE 0x80100003L	Fungsi gagal. Handel yang diteruskan ke fungsi tidak valid.
SEC_E_INVALID_TOKEN 0x80090308L	Fungsi gagal. Token yang diteruskan ke fungsi tidak valid.
SEC_E_LOGON_DENIED 0x8009030CL	Log masuk gagal.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	Fungsi gagal. Tidak ada otoritas yang dapat dihubungi untuk autentikasi. Ini bisa disebabkan oleh kondisi berikut: Nama domain pihak yang mengautentikasi salah. Domain tidak tersedia. Hubungan kepercayaan gagal.
SEC_E_NO_CREDENTIALS 0x8009030EL	Fungsi gagal. Handel kredensial yang ditentukan dalam parameter phCredential tidak valid. Nilai ini dapat dikembalikan saat menggunakan Digest atau Schannel SSP.
SEC_E_OK 0x00000000L	Fungsi berhasil. [konteks keamanan](.. /secgloss/s-gly.md) yang diterima dari klien diterima. Jika token output dihasilkan oleh fungsi, token tersebut harus dikirim ke proses klien.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	Fungsi gagal. Bendera atribut konteks yang tidak valid (ASC_REQ_DELEGATE atau ASC_REQ_PROMPT_FOR_CREDS) ditentukan dalam parameter fContextReq .
SEC_E_APPLICATION_PROTOCOL_MISMATCH 0x80090367L	Tidak ada protokol aplikasi umum antara klien dan server.
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	Fungsi berhasil. Server harus memanggil [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken) dan meneruskan token output ke klien. Server kemudian menunggu token kembali dari klien dan kemudian melakukan panggilan lain ke [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
SEC_I_COMPLETE_NEEDED 0x00090313L	Fungsi berhasil. Server harus selesai membangun pesan dari klien lalu memanggil fungsi [CompleteAuthToken](/windows/win32/api/sspi/nf-sspi-completeauthtoken).
SEC_I_CONTINUE_NEEDED 0x00090312L	Fungsi berhasil. Server harus mengirim token output ke klien dan menunggu token yang dikembalikan. Token yang dikembalikan harus diteruskan dalam pInput untuk panggilan lain ke [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md).
STATUS_LOGON_FAILURE 0xC000006DL	Fungsi gagal. Fungsi [AcceptSecurityContext (Schannel)](acceptsecuritycontext--schannel.md) dipanggil setelah konteks yang ditentukan ditetapkan. Nilai ini dapat dikembalikan saat menggunakan Digest SSP.

Keterangan

Fungsi AcceptSecurityContext (Schannel) adalah rekan server untuk fungsi InitializeSecurityContext (Schannel).

Ketika server menerima permintaan dari klien, server menggunakan parameter fContextReq untuk menentukan apa yang diperlukan sesi. Dengan cara ini, server dapat menentukan bahwa klien harus mampu menggunakan sesi rahasia atau pemeriksaan integritas, dan dapat menolak klien yang tidak dapat memenuhi permintaan tersebut. Atau, server tidak memerlukan apa pun, dan apa pun yang dapat disediakan atau diperlukan klien dikembalikan dalam parameter pfContextAttr .

Untuk paket yang mendukung autentikasi multi-leg, seperti autentikasi timbal balik, urutan panggilan adalah sebagai berikut:

Klien mengirimkan token ke server.
Server memanggil AcceptSecurityContext (Schannel) untuk pertama kalinya, yang menghasilkan token balasan yang kemudian dikirim ke klien.
Klien menerima token dan meneruskannya ke InitializeSecurityContext (Schannel). Jika InitializeSecurityContext (Schannel) mengembalikan SEC_E_OK, autentikasi timbal balik telah selesai dan sesi aman dapat dimulai. Jika InitializeSecurityContext (Schannel) mengembalikan kode kesalahan, negosiasi autentikasi timbal balik berakhir. Jika tidak, token keamanan yang dikembalikan oleh InitializeSecurityContext (Schannel) dikirim ke klien, dan langkah 2 dan 3 diulang.
Jangan gunakan nilai phContext dalam panggilan bersamaan ke AcceptSecurityContext (Schannel). Implementasi di penyedia keamanan tidak aman untuk utas.

Parameter fContextReq dan pfContextAttr adalah bitmask yang mewakili berbagai atribut konteks. Untuk deskripsi berbagai atribut, lihat Persyaratan Konteks.

Catatan

Parameter pfContextAttr valid pada pengembalian yang berhasil, tetapi hanya pada pengembalian akhir yang berhasil jika Anda memeriksa bendera yang berkaitan dengan aspek keamanan konteks. Pengembalian perantara dapat diatur, misalnya, bendera ISC_RET_ALLOCATED_MEMORY.

Pemanggil bertanggung jawab untuk menentukan apakah atribut konteks akhir sudah cukup. Jika, misalnya, kerahasiaan (enkripsi) diminta, tetapi tidak dapat dibuat, beberapa aplikasi dapat memilih untuk segera mematikan koneksi. Jika konteks keamanan tidak dapat dibuat, server harus membebaskan konteks yang dibuat sebagian dengan memanggil fungsi DeleteSecurityContext . Untuk informasi tentang kapan harus memanggil fungsi DeleteSecurityContext , lihat DeleteSecurityContext.

Setelah konteks keamanan ditetapkan, aplikasi server dapat menggunakan fungsi QuerySecurityContextToken untuk mengambil handel ke akun pengguna tempat sertifikat klien dipetakan. Selain itu, server dapat menggunakan fungsi ImpersonateSecurityContext untuk meniru pengguna.

Persyaratan

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

Lihat juga

Fungsi SSPI

DeleteSecurityContext

InitializeSecurityContext (Schannel)

Bagikan melalui