Fungsi InitializeSecurityContext (Umum)

Artikel
03/18/2023

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

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

Untuk informasi tentang menggunakan fungsi ini dengan penyedia dukungan keamanan (SSP) tertentu, lihat topik berikut.

Topik	Deskripsi
InitializeSecurityContext (CredSSP)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan Penyedia Dukungan Keamanan Kredensial (CredSSP).
InitializeSecurityContext (Digest)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan Digest.
InitializeSecurityContext (Kerberos)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan Kerberos.
InitializeSecurityContext (Negosiasi)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan Negosiasi.
InitializeSecurityContext (NTLM)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan NTLM.
InitializeSecurityContext (Schannel)	Memulai sisi klien, konteks keamanan keluar dari handel kredensial dengan menggunakan paket keamanan Schannel.

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 (Umum). Handel ini digunakan untuk membangun konteks keamanan. Fungsi InitializeSecurityContext (Umum) memerlukan setidaknya kredensial OUTBOUND.

phContext[in, optional]

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

Parameter ini bersifat opsional dengan Microsoft Digest SSP dan dapat diatur ke NULL.

Saat menggunakan Schannel SSP, pada panggilan pertama ke InitializeSecurityContext (Umum), tentukan NULL. Pada panggilan mendatang, tentukan token yang diterima dalam parameter phNewContext setelah panggilan pertama ke fungsi ini.

Peringatan

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

pTargetName[in, optional]

Penunjuk ke string yang dihentikan null yang menunjukkan target konteks. Konten string adalah paket keamanan tertentu, seperti yang dijelaskan dalam tabel berikut. Daftar ini tidak lengkap. SSP sistem tambahan dan SSP pihak ketiga dapat ditambahkan ke sistem.

SSP yang digunakan	Makna
Mencerna	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.
Kerberos atau Negosiasi	Nama perwakilan layanan (SPN) atau konteks keamanan server tujuan.
NTLM	Nama perwakilan layanan (SPN) atau konteks keamanan server tujuan.
Schannel/SSL	String null-terminated yang secara unik mengidentifikasi server target. Schannel menggunakan nilai ini untuk memverifikasi sertifikat server. Schannel juga menggunakan nilai ini untuk menemukan sesi dalam cache sesi saat membangun kembali koneksi. Sesi yang di-cache hanya digunakan jika semua kondisi berikut terpenuhi: - Nama targetnya sama. -Entri cache belum kedaluwarsa. -Proses aplikasi yang memanggil fungsi adalah sama. -Sesi masuknya sama. -Handel kredensialnya sama.

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_CONNECTION	Konteks keamanan tidak akan menangani pesan pemformatan. Nilai ini adalah default untuk delegasi yang dibatasiKerberos, Negosiasi, dan NTLM.
ISC_REQ_DELEGATE	Server dapat menggunakan konteks untuk mengautentikasi ke server lain sebagai klien. Bendera ISC_REQ_MUTUAL_AUTH harus diatur agar bendera ini berfungsi. Berlaku untuk Kerberos. Abaikan bendera ini untuk delegasi yang dibatasi.
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_MANUAL_CRED_VALIDATION	Schannel tidak boleh mengautentikasi server secara otomatis.
ISC_REQ_MUTUAL_AUTH	Kebijakan autentikasi bersama layanan akan terpenuhi. PERHATIAN: Ini tidak selalu berarti bahwa autentikasi bersama dilakukan, hanya saja kebijakan autentikasi layanan terpenuhi. Untuk memastikan bahwa autentikasi timbal balik dilakukan, panggil fungsi QueryContextAttributes (Umum).
ISC_REQ_NO_INTEGRITY	Jika bendera ini diatur, bendera ISC_REQ_INTEGRITY diabaikan. Nilai ini hanya didukung oleh delegasi yang dibatasiNegosiasi dan Kerberos.
ISC_REQ_REPLAY_DETECT	Mendeteksi 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.
ISC_REQ_USE_SESSION_KEY	Kunci sesi baru harus dinegosiasikan. Nilai ini hanya didukung oleh delegasi yang dibatasi Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS	Schannel tidak boleh mencoba menyediakan kredensial untuk klien secara otomatis.

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]

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

Parameter ini tidak digunakan dengan Digest atau Schannel. 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.

Dicadangkan2[in]

Parameter ini dicadangkan dan harus diatur ke nol.

phNewContext[in, out, optional]

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke InitializeSecurityContext (Umum), 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.

Saat menggunakan Microsoft Digest SSP, parameter ini menerima respons tantangan yang harus dikirim ke server.

Saat menggunakan Schannel SSP, jika bendera ISC_REQ_ALLOCATE_MEMORY ditentukan, Schannel SSP akan mengalokasikan memori untuk buffer dan menempatkan informasi yang sesuai di SecBufferDesc. Selain itu, pemanggil harus meneruskan buffer jenis SECBUFFER_ALERT. Pada output, jika pemberitahuan dihasilkan, buffer ini berisi informasi tentang pemberitahuan tersebut, dan fungsi gagal.

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 rekan jarak jauh.

ptsExpiry[out, optional]

Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa konteks. Disarankan agar paket keamanan selalu mengembalikan nilai ini di waktu lokal. Parameter ini bersifat opsional dan NULL harus diteruskan untuk klien berumur pendek.

Tidak ada waktu kedaluwarsa untuk kontekskeamanan atau kredensial Microsoft Digest SSP.

Nilai hasil

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

Mengembalikan kode	Deskripsi
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 (Umum).
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 (Umum). Token output dapat 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 yang dipercaya oleh server. Untuk informasi selengkapnya, lihat Keterangan.
SEC_E_INCOMPLETE_MESSAGE	Gunakan dengan Schannel. Data untuk seluruh pesan tidak dibaca dari kawat. Ketika nilai ini dikembalikan, buffer pInput berisi struktur SecBuffer dengan anggota BufferType dari SECBUFFER_MISSING. Anggota cbBuffer secBuffer 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 meningkatkan performa dengan menghindari beberapa panggilan ke fungsi ini.
SEC_E_OK	Konteks keamanan berhasil diinisialisasi. Tidak perlu panggilan InitializeSecurityContext (Umum) lain. Jika fungsi mengembalikan token output, yaitu, jika SECBUFFER_TOKEN dalam pOutput memiliki panjang bukan nol, token tersebut harus dikirim ke server.

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

Mengembalikan 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 kesalahan 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 rusak saat transit, token dengan ukuran yang salah, atau token yang diteruskan ke paket keamanan yang salah. Meneruskan token ke paket yang salah dapat terjadi jika klien dan server tidak menegosiasikan paket keamanan yang tepat.
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 paket keamanan.
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 bersama.

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 (Umum) digunakan oleh klien untuk menginisialisasi konteks keluar.

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

Klien memanggil fungsi dengan phContext yang 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 pointer dalam 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 (Umum).
AcceptSecurityContext (Umum) dapat mengembalikan token, yang dikirim server ke klien untuk panggilan kedua ke InitializeSecurityContext (Umum) jika panggilan pertama dikembalikan SEC_I_CONTINUE_NEEDED.

Untuk kontekskeamanan beberapa 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 (Umum) 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 (Umum). Implementasi di penyedia keamanan tidak aman 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 menengah 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 tersebut.

Tindakan yang diambil klien tergantung pada kode pengembalian dari fungsi ini. Jika kode pengembalian SEC_E_OK, tidak akan ada panggilan InitializeSecurityContext (Umum) 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 (Umum). 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 (Umum) 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 (Umum) lagi setelah berhasil diselesaikan. Ini menunjukkan pada paket keamanan bahwa aauthentikasi 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.

Saat menggunakan Schannel SSP, jika fungsi mengembalikan SEC_I_INCOMPLETE_CREDENTIALS, periksa apakah Anda menentukan sertifikat yang valid dan tepercaya dalam kredensial Anda. Sertifikat ditentukan saat memanggil fungsi AcquireCredentialsHandle (Umum). Sertifikat harus berupa sertifikat autentikasi klien yang dikeluarkan oleh otoritas sertifikasi (CA) yang dipercaya oleh server. Untuk mendapatkan daftar CA yang dipercaya oleh server, panggil fungsi QueryContextAttributes (Umum) dan tentukan atribut SECPKG_ATTR_ISSUER_LIST_EX.

Saat menggunakan Schannel SSP, setelah aplikasi klien menerima sertifikat autentikasi dari CA yang dipercaya oleh server, aplikasi membuat kredensial baru dengan memanggil fungsi AcquireCredentialsHandle (Umum) dan kemudian memanggil InitializeSecurityContext (Umum) lagi, menentukan kredensial baru dalam parameter phCredential.

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
Nama Unicode dan ANSI	InitializeSecurityContextW (Unicode) dan InitializeSecurityContextA (ANSI)

Bagikan melalui

Fungsi InitializeSecurityContext (Umum)

Sintaks

Parameter

Nilai hasil

Keterangan

Persyaratan

Baca juga

Saran dan Komentar

Sumber Daya Tambahan: