Fungsi InitializeSecurityContext (Digest)

Artikel
06/01/2023

Fungsi InitializeSecurityContext (Digest) memulai sisi klien, konteks keamanan keluar dari handel kredensial. Fungsi ini digunakan untuk membangun konteks keamanan antara aplikasi klien dan peer jarak jauh. InitializeSecurityContext (Digest) mengembalikan token yang harus diteruskan klien ke peer jarak jauh, yang pada gilirannya dikirimkan ke implementasi keamanan lokal melalui panggilan AcceptSecurityContext (Digest). Token yang dihasilkan harus dianggap buram oleh semua penelepon.

Biasanya, fungsi InitializeSecurityContext (Digest) dipanggil dalam perulangan hingga konteks keamanan yang memadai ditetapkan.

Sintaks

SECURITY_STATUS SEC_Entry InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        ULONG          fContextReq,
  _In_        ULONG          Reserved1,
  _In_        ULONG          TargetDataRep,
  _In_opt_    PSecBufferDesc pInput,
  _In_        ULONG          Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       PULONG         pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameter

phCredential[in, optional]

Handel ke kredensial yang dikembalikan oleh AcquireCredentialsHandle (Digest). Handel ini digunakan untuk membangun konteks keamanan. Fungsi InitializeSecurityContext (Digest) memerlukan setidaknya kredensial OUTBOUND.

phContext[in, optional]

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke InitializeSecurityContext (Digest), pointer ini adalah NULL. Pada panggilan kedua, parameter ini adalah penunjuk ke handel ke konteks yang terbentuk sebagian yang dikembalikan dalam parameter phNewContext dengan panggilan pertama.

Peringatan

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

pszTargetName[in, optional]

Penunjuk ke string yang dihentikan null yang secara unik mengidentifikasi URI sumber daya yang diminta. String harus terdiri dari karakter yang diizinkan dalam URI dan harus dapat diwakili oleh kumpulan kode ASCII AS. Pengodean persen dapat digunakan untuk mewakili karakter di luar kumpulan kode ASCII AS.

fContextReq[in]

Bendera bit yang menunjukkan permintaan untuk konteks. Tidak semua paket dapat mendukung semua persyaratan. Bendera yang digunakan untuk parameter ini diawali dengan ISC_REQ_, misalnya, ISC_REQ_DELEGATE. Parameter ini dapat berupa satu atau beberapa bendera atribut berikut.

Nilai	Makna
ISC_REQ_ALLOCATE_MEMORY	Paket keamanan mengalokasikan buffer output untuk Anda. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer .
ISC_REQ_CONFIDENTIALITY	Enkripsi pesan dengan menggunakan fungsi EncryptMessage .
ISC_REQ_EXTENDED_ERROR	Ketika kesalahan terjadi, pihak jarak jauh akan diberi tahu.
ISC_REQ_HTTP	Gunakan Digest untuk HTTP. Hilangkan bendera ini untuk menggunakan Digest sebagai mekanisme SASL.
ISC_REQ_INTEGRITY	Tanda tangani pesan dan verifikasi tanda tangan dengan menggunakan fungsi EncryptMessage dan MakeSignature .
ISC_REQ_MUTUAL_AUTH	Kebijakan autentikasi timbal balik layanan akan terpenuhi. HATI: Ini tidak selalu berarti bahwa autentikasi bersama dilakukan, hanya saja kebijakan autentikasi layanan terpenuhi. Untuk memastikan bahwa autentikasi timbal balik dilakukan, panggil fungsi QueryContextAttributes (Digest).
ISC_REQ_REPLAY_DETECT	Deteksi pesan yang diputar ulang yang telah dikodekan dengan menggunakan fungsi EncryptMessage atau MakeSignature .
ISC_REQ_SEQUENCE_DETECT	Mendeteksi pesan yang diterima secara tidak berurutan.
ISC_REQ_STREAM	Mendukung koneksi berorientasi aliran.

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

Untuk deskripsi lebih lanjut tentang berbagai atribut, lihat Persyaratan Konteks.

Dicadangkan1[in]

Parameter ini dicadangkan dan harus diatur ke nol.

TargetDataRep[in]

Parameter ini tidak digunakan dengan Digest. Atur ke nol.

pInput[in, optional]

Penunjuk ke struktur SecBufferDesc yang berisi penunjuk ke buffer yang disediakan sebagai input ke paket. Kecuali konteks klien dimulai oleh server, nilai parameter ini harus berada NULL pada panggilan pertama ke fungsi. Pada panggilan berikutnya ke fungsi atau ketika konteks klien dimulai oleh server, nilai parameter ini adalah penunjuk ke buffer yang dialokasikan dengan memori yang cukup untuk menahan token yang dikembalikan oleh komputer jarak jauh.

Untuk informasi tentang konfigurasi buffer, lihat Buffer Input untuk Respons Tantangan Hash.

Dicadangkan2[in]

Parameter ini dicadangkan dan harus diatur ke nol.

phNewContext[in, out, optional]

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

pOutput[in, out, optional]

Penunjuk ke struktur SecBufferDesc yang berisi penunjuk ke struktur SecBuffer yang menerima data output. Jika buffer diketik sebagai SEC_READWRITE dalam input, buffer akan berada di sana pada output. Sistem akan mengalokasikan buffer untuk token keamanan jika diminta (melalui ISC_REQ_ALLOCATE_MEMORY) dan mengisi alamat di deskriptor buffer untuk token keamanan.

Parameter ini menerima respons tantangan yang harus dikirim ke server.

pfContextAttr[out]

Penunjuk ke variabel untuk 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 ISC_RET, seperti ISC_RET_DELEGATE. Untuk daftar nilai yang valid, lihat parameter fContextReq .

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.

Catatan

Atribut konteks tertentu dapat berubah selama negosiasi dengan peer jarak jauh.

ptsExpiry[out, optional]

Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa konteks.

Tidak ada waktu kedaluwarsa untuk konteks keamananatau kredensial Microsoft Digest SSP.

Nilai kembali

Jika fungsi berhasil, fungsi mengembalikan salah satu kode keberhasilan berikut.

Menampilkan kode	Deskripsi
SEC_E_OK	Konteks keamanan berhasil diinisialisasi. Tidak perlu panggilan InitializeSecurityContext (Digest) lain. Jika fungsi mengembalikan token output, yaitu, jika SECBUFFER_TOKEN dalam pOutput memiliki panjang bukan nol, token tersebut harus dikirim ke server.
SEC_I_COMPLETE_AND_CONTINUE	Klien harus memanggil CompleteAuthToken lalu meneruskan output ke server. Klien kemudian menunggu token yang dikembalikan dan meneruskannya, dalam panggilan lain, ke InitializeSecurityContext (Digest).
SEC_I_COMPLETE_NEEDED	Klien harus selesai membangun pesan lalu memanggil fungsi CompleteAuthToken .
SEC_I_CONTINUE_NEEDED	Klien harus mengirim token output ke server dan menunggu token kembali. Token yang dikembalikan kemudian diteruskan dalam panggilan lain ke InitializeSecurityContext (Digest). Token output bisa kosong.
SEC_I_INCOMPLETE_CREDENTIALS	Gunakan dengan Schannel. Server telah meminta autentikasi klien, dan kredensial yang disediakan tidak menyertakan sertifikat atau sertifikat tidak dikeluarkan oleh otoritas sertifikasi (CA) yang dipercaya oleh server. Untuk informasi selengkapnya, lihat Keterangan.

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

Menampilkan kode	Deskripsi
SEC_E_INSUFFICIENT_MEMORY	Tidak tersedia cukup memori untuk menyelesaikan tindakan yang diminta.
SEC_E_INTERNAL_ERROR	Terjadi kesalahan yang tidak memetakan ke kode galat SSPI.
SEC_E_INVALID_HANDLE	Handel yang diteruskan ke fungsi tidak valid.
SEC_E_INVALID_TOKEN	Kesalahan ini disebabkan oleh token input yang salah bentuk, seperti token yang rusak saat transit, token dengan ukuran yang salah, atau token yang diteruskan ke delegasi yang dibatasi salah. Meneruskan token ke paket yang salah dapat terjadi jika klien dan server tidak menegosiasikan delegasi yang dibatasi dengan benar.
SEC_E_LOGON_DENIED	Log masuk gagal.
SEC_E_NO_AUTHENTICATING_AUTHORITY	Tidak ada otoritas yang dapat dihubungi untuk autentikasi. Nama domain pihak yang mengautentikasi bisa salah, domain mungkin tidak dapat dijangkau, atau mungkin ada kegagalan hubungan kepercayaan.
SEC_E_NO_CREDENTIALS	Tidak ada kredensial yang tersedia dalam delegasi yang dibatasi.
SEC_E_TARGET_UNKNOWN	Target tidak dikenali.
SEC_E_UNSUPPORTED_FUNCTION	Bendera atribut konteks yang tidak valid (ISC_REQ_DELEGATE atau ISC_REQ_PROMPT_FOR_CREDS) ditentukan dalam parameter fContextReq .
SEC_E_WRONG_PRINCIPAL	Prinsipal yang menerima permintaan autentikasi tidak sama dengan yang diteruskan ke parameter pszTargetName . Ini menunjukkan kegagalan dalam autentikasi timbal balik.

Keterangan

Pemanggil bertanggung jawab untuk menentukan apakah atribut konteks akhir sudah cukup. Jika, misalnya, kerahasiaan diminta, tetapi tidak dapat dibuat, beberapa aplikasi dapat memilih untuk segera mematikan koneksi.

Jika atribut konteks keamanan tidak memadai, klien harus membebaskan konteks yang dibuat sebagian dengan memanggil fungsi DeleteSecurityContext .

Fungsi InitializeSecurityContext (Digest) digunakan oleh klien untuk menginisialisasi konteks keluar.

Untuk konteks keamanan dua kaki, urutan panggilan adalah sebagai berikut:

Klien memanggil fungsi dengan phContext diatur ke NULL dan mengisi deskriptor buffer dengan pesan input.
Paket keamanan memeriksa parameter dan membuat token buram, menempatkannya di elemen TOKEN dalam array buffer. Jika parameter fContextReq menyertakan bendera ISC_REQ_ALLOCATE_MEMORY, paket keamanan mengalokasikan memori dan mengembalikan penunjuk di elemen TOKEN.
Klien mengirim token yang dikembalikan dalam buffer pOutput ke server target. Server kemudian meneruskan token sebagai argumen input dalam panggilan ke fungsi AcceptSecurityContext (Digest).
AcceptSecurityContext (Digest) dapat mengembalikan token, yang dikirim server ke klien untuk panggilan kedua ke InitializeSecurityContext (Digest) jika panggilan pertama dikembalikan SEC_I_CONTINUE_NEEDED.

Untuk konteks keamananmulti-kaki, seperti autentikasi timbal balik, urutan panggilan adalah sebagai berikut:

Klien memanggil fungsi seperti yang dijelaskan sebelumnya, tetapi paket mengembalikan kode keberhasilan SEC_I_CONTINUE_NEEDED.
Klien mengirim token output ke server dan menunggu balasan server.
Setelah menerima respons server, klien memanggil InitializeSecurityContext (Digest) lagi, dengan phContext diatur ke handel yang dikembalikan dari panggilan terakhir. Token yang diterima dari server disediakan dalam parameter pInput .
Jangan gunakan nilai phContext dalam panggilan bersamaan ke InitializeSecurityContext (Digest). Implementasi di penyedia keamanan tidak aman untuk utas.

Jika server berhasil merespons, paket keamanan mengembalikan SEC_E_OK dan sesi aman dibuat.

Jika fungsi mengembalikan salah satu respons kesalahan, respons server tidak diterima, dan sesi tidak dibuat.

Jika fungsi mengembalikan SEC_I_CONTINUE_NEEDED, SEC_I_COMPLETE_NEEDED, atau SEC_I_COMPLETE_AND_CONTINUE, langkah 2 dan 3 diulang.

Untuk menginisialisasi konteks keamanan, mungkin diperlukan lebih dari satu panggilan ke fungsi ini, tergantung pada mekanisme autentikasi yang mendasar serta pilihan yang ditentukan dalam parameter fContextReq .

Parameter fContextReq dan pfContextAttributes adalah bitmask yang mewakili berbagai atribut konteks. Untuk deskripsi berbagai atribut, lihat Persyaratan Konteks. Parameter pfContextAttributes 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.

Jika bendera ISC_REQ_USE_SUPPLIED_CREDS diatur, paket keamanan harus mencari jenis buffer SECBUFFER_PKG_PARAMS di buffer input pInput . Ini bukan solusi umum, tetapi memungkinkan pemasangan paket dan aplikasi keamanan yang kuat jika sesuai.

Jika ISC_REQ_ALLOCATE_MEMORY ditentukan, pemanggil harus membebaskan memori dengan memanggil fungsi FreeContextBuffer .

Misalnya, token input bisa menjadi tantangan dari Manajer LAN. Dalam hal ini, token output akan menjadi respons terenkripsi NTLM terhadap tantangan.

Tindakan yang dilakukan klien tergantung pada kode pengembalian dari fungsi ini. Jika kode pengembalian SEC_E_OK, tidak akan ada panggilan InitializeSecurityContext (Digest) kedua, dan tidak ada respons dari server yang diharapkan. Jika kode pengembalian SEC_I_CONTINUE_NEEDED, klien mengharapkan token sebagai respons dari server dan meneruskannya dalam panggilan kedua ke InitializeSecurityContext (Digest). Kode pengembalian SEC_I_COMPLETE_NEEDED menunjukkan bahwa klien harus selesai membangun pesan dan memanggil fungsi CompleteAuthToken . Kode SEC_I_COMPLETE_AND_CONTINUE menggabungkan kedua tindakan ini.

Jika InitializeSecurityContext (Digest) mengembalikan keberhasilan pada panggilan pertama (atau hanya), pemanggil akhirnya harus memanggil fungsi DeleteSecurityContext pada handel yang dikembalikan, bahkan jika panggilan gagal pada bagian pertukaran autentikasi nanti.

Klien dapat memanggil InitializeSecurityContext (Digest) lagi setelah berhasil diselesaikan. Ini menunjukkan pada paket keamanan bahwa aautotikasi ulang diinginkan.

Pemanggil mode kernel memiliki perbedaan berikut: nama target adalah string Unicode yang harus dialokasikan dalam memori virtual dengan menggunakan VirtualAlloc; tidak boleh dialokasikan dari kumpulan. Buffer yang diteruskan dan disediakan dalam pInput dan pOutput harus dalam memori virtual, bukan di kumpulan.

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