InitializeSecurityContextA (sspi.h)
Fungsi InitializeSecurityContext (Umum) memulai sisi klien, konteks keamanan keluar dari handel kredensial. Fungsi ini digunakan untuk membangun konteks keamanan antara aplikasi klien dan peer jarak jauh. InitializeSecurityContext (Umum) mengembalikan token yang harus diteruskan klien ke peer jarak jauh, yang pada gilirannya dikirimkan 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 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 InitializeSecurityContextA(
[in, optional] PCredHandle phCredential,
[in, optional] PCtxtHandle phContext,
SEC_CHAR *pszTargetName,
[in] unsigned long fContextReq,
[in] unsigned long Reserved1,
[in] unsigned long TargetDataRep,
[in, optional] PSecBufferDesc pInput,
[in] unsigned long Reserved2,
[in, out, optional] PCtxtHandle phNewContext,
[in, out, optional] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Parameter
[in, optional] phCredential
Handel ke kredensial yang dikembalikan oleh AcquireCredentialsHandle (Umum). Handel ini digunakan untuk membangun konteks keamanan. Fungsi InitializeSecurityContext (Umum) memerlukan setidaknya kredensial OUTBOUND.
[in, optional] phContext
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 terbentuk sebagian yang dikembalikan dalam parameter phNewContext dengan 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.
pszTargetName
TBD
[in] fContextReq
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 |
---|---|
|
Paket keamanan mengalokasikan buffer output untuk Anda. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer . |
|
Enkripsi pesan dengan menggunakan fungsi EncryptMessage . |
|
Konteks keamanan tidak akan menangani pesan pemformatan. Nilai ini adalah default untuk paket keamanan Kerberos, Negosiasi, dan NTLM. |
|
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. |
|
Ketika kesalahan terjadi, pihak jarak jauh akan diberi tahu. |
|
Gunakan Digest untuk HTTP. Hilangkan bendera ini untuk menggunakan Digest sebagai mekanisme SASL. |
|
Tanda tangani pesan dan verifikasi tanda tangan dengan menggunakan fungsi EncryptMessage dan MakeSignature . |
|
Schannel tidak boleh mengautentikasi server secara otomatis. |
|
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 (Umum).
|
|
Jika bendera ini diatur, bendera ISC_REQ_INTEGRITY diabaikan.
Nilai ini hanya didukung oleh paket keamanan Negosiasi dan Kerberos. |
|
Deteksi pesan yang diputar ulang yang telah dikodekan dengan menggunakan fungsi EncryptMessage atau MakeSignature . |
|
Mendeteksi pesan yang diterima secara tidak berurutan. |
|
Mendukung koneksi berorientasi aliran. |
|
Kunci sesi baru harus dinegosiasikan.
Nilai ini hanya didukung oleh paket keamanan Kerberos. |
|
Schannel tidak boleh mencoba untuk 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.
[in] Reserved1
Parameter ini dicadangkan dan harus diatur ke nol.
[in] TargetDataRep
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.
[in, optional] pInput
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 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.
[in] Reserved2
Parameter ini dicadangkan dan harus diatur ke nol.
[in, out, optional] phNewContext
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 .
Saat menggunakan Schannel SSP, pada panggilan setelah panggilan pertama, lewati handel yang dikembalikan di sini sebagai parameter phContext dan tentukan NULL untuk phNewContext.
[in, out, optional] pOutput
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, penelepon harus meneruskan buffer jenis SECBUFFER_ALERT. Pada output, jika pemberitahuan dibuat, buffer ini berisi informasi tentang pemberitahuan tersebut, dan fungsi gagal.
[out] pfContextAttr
Penunjuk ke variabel untuk menerima sekumpulan bendera bit yang menunjukkan atributkonteks 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.
[out, optional] ptsExpiry
Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa konteks. Disarankan agar paket keamanan selalu mengembalikan nilai ini di waktu setempat. Parameter ini bersifat opsional dan NULL harus diteruskan untuk klien berumur pendek.
Tidak ada waktu kedaluwarsa untuk konteks atau kredensial keamanan Microsoft Digest SSP.
Mengembalikan nilai
Jika fungsi berhasil, fungsi mengembalikan salah satu kode keberhasilan berikut.
Menampilkan kode | Deskripsi |
---|---|
|
Klien harus memanggil CompleteAuthToken lalu meneruskan output ke server. Klien kemudian menunggu token yang dikembalikan dan meneruskannya, dalam panggilan lain, ke InitializeSecurityContext (Umum). |
|
Klien harus selesai membangun pesan lalu memanggil fungsi CompleteAuthToken . |
|
Klien harus mengirim token output ke server dan menunggu token kembali. Token yang dikembalikan kemudian diteruskan dalam panggilan lain ke InitializeSecurityContext (Umum). Token output bisa kosong. |
|
Gunakan dengan Schannel. Server telah meminta autentikasi klien, dan kredensial yang diberikan tidak menyertakan sertifikat atau sertifikat tidak dikeluarkan oleh otoritas sertifikasi yang dipercaya oleh server. Untuk informasi selengkapnya, lihat Keterangan. |
|
Gunakan dengan Schannel. Data untuk seluruh pesan tidak dibaca dari kabel.
Ketika nilai ini dikembalikan, buffer pInput berisi struktur SecBuffer dengan anggota BufferTypedari SECBUFFER_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 meningkatkan performa dengan menghindari beberapa panggilan ke fungsi ini. |
|
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.
Menampilkan kode | Deskripsi |
---|---|
|
Tidak tersedia cukup memori untuk menyelesaikan tindakan yang diminta. |
|
Terjadi kesalahan yang tidak memetakan ke kode kesalahan SSPI. |
|
Handel yang diteruskan ke fungsi tidak valid. |
|
Kesalahan ini disebabkan oleh token input yang salah bentuk, seperti token yang rusak saat transit, token 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. |
|
Log masuk gagal. |
|
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. |
|
Tidak ada kredensial yang tersedia dalam paket keamanan. |
|
Target tidak dikenali. |
|
Bendera atribut konteks yang tidak valid (ISC_REQ_DELEGATE atau ISC_REQ_PROMPT_FOR_CREDS) ditentukan dalam parameter fContextReq . |
|
Prinsipal yang menerima permintaan autentikasi tidak sama dengan yang diteruskan ke parameter pszTargetName . Ini menunjukkan kegagalan dalam autentikasi bersama. |
Keterangan
Penelepon 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 cukup, 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 diatur ke NULL dan mengisi deskriptor buffer dengan pesan input.
- Paket keamanan memeriksa parameter dan membangun 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 di 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.
- 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 .
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 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 selanjutnya dari pertukaran autentikasi.
Klien dapat memanggil InitializeSecurityContext (Umum) lagi setelah berhasil diselesaikan. Hal 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 berada 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 merupakan 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 .
Catatan
Header sspi.h mendefinisikan InitializeSecurityContext sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.
Persyaratan
Persyaratan | Nilai |
---|---|
Klien minimum yang didukung | Windows XP [hanya aplikasi desktop] |
Server minimum yang didukung | Windows Server 2003 [hanya aplikasi desktop] |
Target Platform | Windows |
Header | sspi.h (termasuk Security.h) |
Pustaka | Secur32.lib |
DLL | Secur32.dll |