Fungsi AcceptSecurityContext (Digest)
Fungsi AcceptSecurityContext (Digest) memungkinkan komponen server aplikasi transportasi untuk membangun konteks keamanan antara server dan klien jarak jauh. Klien jarak jauh menggunakan fungsi InitializeSecurityContext (Digest) 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,
_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 ptsExpiry
);
Parameter
phCredential [in, optional]
Handel ke kredensial server. Server memanggil fungsi AcquireCredentialsHandle (Digest) dengan bendera SECPKG_CRED_INBOUND atau SECPKG_CRED_BOTH yang diatur untuk mengambil handel ini.
phContext [in, out, optional]
Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke AcceptSecurityContext (Digest), pointer ini adalah NULL. Pada panggilan berikutnya, phContext adalah handel ke konteks yang dibentuk sebagian yang dikembalikan dalam parameter phNewContext oleh panggilan pertama.
Peringatan
Jangan gunakan handel konteks yang sama dalam panggilan bersamaan ke AcceptSecurityContext (Digest). Implementasi API di penyedia layanan keamanan tidak aman untuk utas.
pInput [in, optional]
Penunjuk ke struktur SecBufferDesc yang dihasilkan oleh panggilan klien ke InitializeSecurityContext (Digest) yang berisi deskriptor buffer input.
Tabel berikut menunjukkan konfigurasi buffer untuk Digest HTTP. Buffer pertama harus berjenis SECBUFFER_TOKEN, dan sisanya harus berjenis SECBUFFER_PKG_PARAMS. SASL hanya memerlukan buffer zero.
| Jenis buffer #/buffer | Makna |
|---|---|
| 0 SECBUFFER_TOKEN |
Kosong untuk panggilan pertama dan respons tantangan yang diterima dari klien untuk panggilan kedua. |
| 1 SECBUFFER_PKG_PARAMS |
Metode. Karakter adalah format wireline dari baris permintaan. Karakter byte tunggal ASCII ASCII. |
| 2 SECBUFFER_PKG_PARAMS |
Dicadangkan. |
| 3
SECBUFFER_PKG_PARAMS |
HEntity. Representasi heksadesimal dari H(entity-body). Karakter byte tunggal ASCII ASCII. |
| 4
SECBUFFER_PKG_PARAMS |
Ranah. String realm untuk tantangan. String Unicode yang harus dapat diwakili di ASCII ASCII. |
| 5
| SECBUFFER_READONLY SECBUFFER_CHANNEL_BINDINGS |
Berisi nilai token pengikatan saluran. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
fContextReq [in]
Bendera bit 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 | Digest mengalokasikan buffer output untuk Anda. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer . |
| ASC_REQ_ALLOW_MISSING_BINDINGS | Menunjukkan bahwa Digest tidak memerlukan pengikatan saluran untuk saluran dalam dan luar. Nilai ini digunakan untuk kompatibilitas mundur ketika dukungan untuk pengikatan saluran titik akhir tidak diketahui. Nilai ini saling eksklusif dengan ASC_REQ_PROXY_BINDINGS. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
| ASC_REQ_CONFIDENTIALITY | Mengenkripsi dan mendekripsi pesan. SSP Digest hanya mendukung bendera ini untuk SASL. |
| ASC_REQ_PROXY_BINDINGS | Menunjukkan bahwa Digest memerlukan pengikatan saluran. Nilai ini saling eksklusif dengan ASC_REQ_ALLOW_MISSING_BINDINGS. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung. |
| ASC_REQ_CONNECTION | Konteks keamanan tidak akan menangani pesan pemformatan. |
| ASC_REQ_EXTENDED_ERROR | Ketika kesalahan terjadi, pihak jarak jauh akan diberi tahu. |
| ASC_REQ_HTTP (0x10000000) | Gunakan Digest untuk HTTP. Hilangkan bendera ini untuk menggunakan Digest sebagai mekanisme SASL. |
| ASC_REQ_INTEGRITY | Menandatangani pesan dan memverifikasi tanda tangan. |
| ASC_REQ_REPLAY_DETECT | Mendeteksi paket yang diputar ulang. |
| ASC_REQ_SEQUENCE_DETECT | Mendeteksi pesan yang diterima secara tidak berurutan. |
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.
Parameter ini tidak digunakan dengan Digest SSP. Saat Anda menggunakan Digest SSP, tentukan nol untuk parameter ini.
phNewContext [in, out, optional]
Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke AcceptSecurityContext (Digest), 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 (Digest). Buffer output dapat dihasilkan meskipun fungsi mengembalikan SEC_E_OK. Setiap buffer yang dihasilkan harus dikirim kembali ke aplikasi klien.
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 lokal.
Parameter ini diatur ke waktu maksimum konstanta. Tidak ada waktu kedaluwarsa untuk kontekskeamanan Digest atau kredensial atau saat menggunakan Digest SSP.
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_INSUFFICIENT_MEMORY0x80090300L |
Fungsi gagal. Tidak tersedia cukup memori untuk menyelesaikan tindakan yang diminta. |
SEC_E_INTERNAL_ERROR0x80090304L |
Fungsi gagal. Terjadi kesalahan yang tidak memetakan ke kode kesalahan SSPI. |
SEC_E_INVALID_HANDLE0x80100003L |
Fungsi gagal. Handel yang diteruskan ke fungsi tidak valid. |
SEC_E_INVALID_TOKEN0x80090308L |
Fungsi gagal. Token yang diteruskan ke fungsi tidak valid. |
SEC_E_LOGON_DENIED0x8009030CL |
Log masuk gagal. |
SEC_E_NO_AUTHENTICATING_AUTHORITY0x80090311L |
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 telah gagal. |
SEC_E_NO_CREDENTIALS0x8009030EL |
Fungsi gagal. Handel kredensial yang ditentukan dalam parameter phCredential tidak valid. |
SEC_E_OK0x00000000L |
Fungsi berhasil. Konteks keamanan yang diterima dari klien diterima. Jika token output dihasilkan oleh fungsi, token tersebut harus dikirim ke proses klien. |
SEC_E_SECURITY_QOS_FAILED0x80090332L |
Fungsi gagal. Bendera atribut konteks yang tidak valid ditentukan dalam parameter fContextReq . |
SEC_I_COMPLETE_AND_CONTINUE0x00090314L |
Fungsi berhasil. Server harus memanggil CompleteAuthToken dan meneruskan token output ke klien. Server kemudian menunggu token kembali dari klien dan kemudian melakukan panggilan lain ke AcceptSecurityContext (Digest). |
SEC_I_COMPLETE_NEEDED0x00090313L |
Fungsi berhasil. Server harus selesai membangun pesan dari klien lalu memanggil fungsi CompleteAuthToken . |
SEC_I_CONTINUE_NEEDED0x00090312L |
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 (Digest). |
STATUS_LOGON_FAILURE0xC000006DL |
Fungsi gagal. Fungsi AcceptSecurityContext (Digest) dipanggil setelah konteks yang ditentukan ditetapkan. |
SEC_E_BAD_BINDINGS0x80090346L |
Fungsi gagal. Kebijakan pengikatan saluran tidak terpenuhi. |
Keterangan
Fungsi AcceptSecurityContext (Digest) adalah rekan server untuk fungsi InitializeSecurityContext (Digest).
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 (Digest) pertama kalinya, yang menghasilkan token balasan yang kemudian dikirim ke klien.
- Klien menerima token dan meneruskannya ke InitializeSecurityContext (Digest). Jika InitializeSecurityContext (Digest) mengembalikan SEC_E_OK, autentikasi timbal balik telah selesai dan sesi aman dapat dimulai. Jika InitializeSecurityContext (Digest) mengembalikan kode kesalahan, negosiasi autentikasi timbal balik berakhir. Jika tidak, token keamanan yang dikembalikan oleh InitializeSecurityContext (Digest) dikirim ke klien, dan langkah 2 dan 3 diulang.
- Jangan gunakan nilai phContext dalam panggilan bersamaan ke AcceptSecurityContext (Digest). Implementasi di penyedia keamanan tidak aman 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 menengah 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 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 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 |
Lihat juga
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk