Bagikan melalui

Fungsi AcceptSecurityContext (CredSSP)

  • Artikel

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

Sintaks

SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        unsigned long  fContextReq,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameter

phCredential [in, optional]

Handel ke kredensial server. Untuk mengambil handel ini, server memanggil fungsi AcquireCredentialsHandle (CredSSP) dengan set bendera SECPKG_CRED_INBOUND atau SECPKG_CRED_BOTH.

phContext [in, optional]

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

Peringatan

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

pInput [in, optional]

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

Buffer pertama harus berjenis SECBUFFER_TOKEN dan berisi token keamanan yang diterima dari klien. Buffer kedua harus berjenis SECBUFFER_EMPTY.

fContextReq [in]

-Bit bendera yang menentukan atribut yang diperlukan oleh server untuk membuat konteks. Bendera bit dapat dikombinasikan dengan menggunakan operasi bitwise-OR. Parameter ini bisa berupa satu atau beberapa nilai berikut.

Nilai Makna
ASC_REQ_ALLOCATE_MEMORY Penyedia Dukungan Keamanan Kredensial (CredSSP) akan mengalokasikan buffer output. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer .
ASC_REQ_CONNECTION Konteks keamanan tidak akan menangani pesan pemformatan.
ASC_REQ_DELEGATE Server diizinkan untuk meniru klien. Abaikan bendera ini untuk delegasi yang dibatasi.
ASC_REQ_EXTENDED_ERROR Ketika kesalahan terjadi, pihak jarak jauh akan diberi tahu.
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.

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]

Representasi data, seperti pengurutan byte, pada target. Parameter ini dapat berupa SECURITY_NATIVE_DREP atau SECURITY_NETWORK_DREP.

phNewContext [in, out, optional]

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

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 (CredSSP). 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.

pfContextAttr [out]

Penunjuk ke 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.

ptsExpiry [out, optional]

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

Catatan

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

Nilai hasil

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 (CredSSP) lagi.
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 kesalahan 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.
SEC_E_OK
0x00000000L		 Fungsi berhasil. Konteks keamanan yang diterima dari klien diterima. Jika fungsi menghasilkan token output, token harus dikirim ke proses klien.
SEC_E_UNSUPPORTED_FUNCTION
0x80090302L		 Fungsi gagal. Parameter fContextReq menentukan bendera atribut konteks (ASC_REQ_DELEGATE atau ASC_REQ_PROMPT_FOR_CREDS) yang tidak valid.
SEC_I_COMPLETE_AND_CONTINUE
0x00090314L		 Fungsi berhasil. Server harus memanggil CompleteAuthToken dan meneruskan token output ke klien. Server kemudian harus menunggu token pengembalian dari klien sebelum melakukan panggilan lain ke AcceptSecurityContext (CredSSP).
SEC_I_COMPLETE_NEEDED
0x00090313L		 Fungsi berhasil. Server harus selesai membangun pesan dari klien sebelum memanggil 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 (CredSSP).

Keterangan

Fungsi AcceptSecurityContext (CredSSP) adalah mitra server untuk fungsi InitializeSecurityContext (CredSSP).

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

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

Catatan

Meskipun parameter pfContextAttr valid pada pengembalian yang berhasil, Anda harus memeriksa bendera yang berkaitan dengan aspek keamanan konteks hanya pada pengembalian akhir yang berhasil. Pengembalian menengah dapat diatur, misalnya, bendera ISC_RET_ALLOCATED_MEMORY.

Pemanggil bertanggung jawab untuk menentukan apakah atribut konteks akhir sudah cukup. Misalnya, jika 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 dibuat, 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 Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Header Sspi.h (termasuk Security.h)
Pustaka Secur32.lib
DLL Secur32.dll

Lihat juga