InitializeSecurityContextA (sspi.h)

  • Artikel

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
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 paket keamanan Kerberos, 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 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).
 
ISC_REQ_NO_INTEGRITY
 Jika bendera ini diatur, bendera ISC_REQ_INTEGRITY diabaikan.

Nilai ini hanya didukung oleh paket keamanan Negosiasi dan Kerberos.
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.
ISC_REQ_USE_SESSION_KEY
 Kunci sesi baru harus dinegosiasikan.

Nilai ini hanya didukung oleh paket keamanan Kerberos.
ISC_REQ_USE_SUPPLIED_CREDS
 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.

Catatan Atribut konteks tertentu dapat berubah selama negosiasi dengan rekan jarak jauh.
 

[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
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 bisa kosong.
SEC_I_INCOMPLETE_CREDENTIALS
 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.
SEC_E_INCOMPLETE_MESSAGE
 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.
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.

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

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:

  1. Klien memanggil fungsi dengan phContext diatur ke NULL dan mengisi deskriptor buffer dengan pesan input.
  2. 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.
  3. Klien mengirim token yang dikembalikan di buffer pOutput ke server target. Server kemudian meneruskan token sebagai argumen input dalam panggilan ke fungsi AcceptSecurityContext (Umum).
  4. 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 konteks keamanan multi-kaki, seperti autentikasi timbal balik, urutan panggilan adalah sebagai berikut:
  1. Klien memanggil fungsi seperti yang dijelaskan sebelumnya, tetapi paket mengembalikan kode keberhasilan SEC_I_CONTINUE_NEEDED.
  2. Klien mengirim token output ke server dan menunggu balasan server.
  3. 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 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 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

Lihat juga

AcceptSecurityContext (Umum)

AcquireCredentialsHandle (Umum)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

Fungsi SSPI

SecBuffer

SecBufferDesc