Bagikan melalui

Fungsi InitializeSecurityContext (CredSSP)

  • Artikel

Fungsi InitializeSecurityContext (CredSSP) memulai sisi klien, konteks keamanan keluar dari handel kredensial. Fungsi ini membangun konteks keamanan antara aplikasi klien dan serekan jarak jauh. InitializeSecurityContext (CredSSP) mengembalikan token yang harus diteruskan klien ke peer jarak jauh; serekan pada gilirannya mengirimkan token tersebut ke implementasi keamanan lokal melalui panggilan AcceptSecurityContext (CredSSP ). Token yang dihasilkan harus dianggap buram oleh semua pemanggil.

Biasanya, fungsi InitializeSecurityContext (CredSSP) 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_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

Parameter

phCredential[in, optional]

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

phContext[in, optional]

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

Pada panggilan pertama ke InitializeSecurityContext (CredSSP), 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 (CredSSP). Implementasi API di penyedia layanan keamanan tidak aman untuk utas.

pTargetName[in, optional]

Penunjuk ke string yang dihentikan null 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 cache hanya digunakan jika semua kondisi berikut terpenuhi:

  • Nama target sama.
  • Entri singgahan belum kedaluwarsa.
  • Proses aplikasi yang memanggil fungsi adalah sama.
  • Sesi masuk 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
0x100		 Paket keamanan mengalokasikan buffer output untuk pemanggil. Setelah Anda selesai menggunakan buffer output, bebaskan dengan memanggil fungsi FreeContextBuffer .
ISC_REQ_CONNECTION
0x800		 Konteks keamanan tidak akan menangani pesan pemformatan.
ISC_REQ_EXTENDED_ERROR
0x4000		 Ketika terjadi kesalahan, pihak jarak jauh akan diberi tahu.
ISC_REQ_MANUAL_CRED_VALIDATION
0x80000		 Penyedia Dukungan Keamanan Kredensial (CredSSP) tidak boleh mengautentikasi server secara otomatis. Bendera ini selalu diatur saat menggunakan CredSSP.
ISC_REQ_SEQUENCE_DETECT
0x8		 Mendeteksi pesan yang diterima secara tidak berurutan.
ISC_REQ_STREAM
0x8000		 Mendukung koneksi berorientasi aliran.
ISC_REQ_USE_SUPPLIED_CREDS
0x80		 CredSSP tidak boleh mencoba menyediakan kredensial untuk klien secara otomatis.
ISC_REQ_DELEGATE
0x1		 Menunjukkan bahwa kredensial pengguna akan didelegasikan ke server.
Jika bendera ini tidak ditentukan, set kredensial kosong didelegasikan ke server.
Windows Server 2008 dan Windows Vista: Bendera ini diperlukan.
ISC_REQ_MUTUAL_AUTH
0x2		 Menunjukkan bahwa autentikasi server tidak diperlukan. Kebijakan delegasi masih diberlakukan jika bendera ini tidak ditentukan.
Windows Server 2008 dan Windows Vista: Bendera ini diabaikan.

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]

Dicadangkan. Parameter ini harus diatur ke nol.

TargetDataRep[in]

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

pInput[in, out, optional]

Penunjuk ke struktur SecBufferDesc yang berisi pointer 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.

Pada panggilan ke fungsi ini setelah panggilan awal, harus ada dua buffer. Yang pertama memiliki jenis SECBUFFER_TOKEN dan berisi token yang diterima dari server. Buffer kedua memiliki jenis SECBUFFER_EMPTY; atur anggota pvBuffer dan cbBuffer ke nol.

Dicadangkan2[in]

Dicadangkan. Parameter ini harus diatur ke nol.

phNewContext[in, out, optional]

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

pOutput[out, optional]

Penunjuk ke struktur SecBufferDesc . Struktur ini pada gilirannya berisi pointer 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.

Jika bendera ISC_REQ_ALLOCATE_MEMORY ditentukan, CredSSP akan mengalokasikan memori untuk buffer dan menempatkan informasi yang sesuai di SecBufferDesc.

pfContextAttr[out]

Penunjuk ke 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 setempat. Parameter ini bersifat opsional dan NULL harus diteruskan untuk klien berumur pendek.

Nilai kembali

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

Menampilkan kode Deskripsi
SEC_E_INCOMPLETE_MESSAGE Data untuk seluruh pesan tidak dibaca dari kabel.
Ketika nilai ini dikembalikan, buffer pInput berisi struktur SecBuffer dengan anggota BufferTypedari SECBUFFER_MISSING. Anggota cbBuffersecBuffer menentukan 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 (CredSSP) 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 (CredSSP).
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. Klien meneruskan token yang dikembalikan dalam panggilan lain ke InitializeSecurityContext (CredSSP). Token output bisa kosong.
SEC_I_INCOMPLETE_CREDENTIALS Server telah meminta autentikasi klien, tetapi kredensial yang diberikan tidak menyertakan sertifikat, atau sertifikat tidak dikeluarkan oleh otoritas sertifikasi yang dipercaya 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 kesalahan SSPI.
SEC_E_INVALID_HANDLE Handel yang diteruskan ke fungsi tidak valid.
SEC_E_INVALID_TOKEN Token input cacat . Kemungkinan penyebabnya termasuk token yang rusak saat transit, token ukuran yang salah, dan token yang diteruskan ke paket keamanan yang salah. Kondisi terakhir ini 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 Nilai parameter fContextReq tidak valid. Bendera yang diperlukan tidak ditentukan, atau bendera yang tidak didukung oleh CredSSP ditentukan.
SEC_E_WRONG_PRINCIPAL Prinsipal yang menerima permintaan autentikasi tidak sama dengan yang diteruskan ke parameter pszTargetName . Kesalahan ini menunjukkan kegagalan dalam autentikasi bersama.
SEC_E_DELEGATION_POLICY Kebijakan ini tidak mendukung delegasi kredensial ke server target.
SEC_E_POLICY_NLTM_ONLY Delegasi kredensial ke server target tidak diperbolehkan ketika autentikasi bersama tidak tercapai.
SEC_E_MUTUAL_AUTH_FAILED Autentikasi server gagal ketika bendera ISC_REQ_MUTUAL_AUTH ditentukan dalam parameter fContextReq .

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 .

Klien memanggil fungsi InitializeSecurityContext (CredSSP) 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 dalam 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 (CredSSP).
  4. AcceptSecurityContext (CredSSP) dapat mengembalikan token. Server mengirimkan token ini ke klien melalui panggilan InitializeSecurityContext (CredSSP) kedua jika panggilan pertama dikembalikan SEC_I_CONTINUE_NEEDED.

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.

Inisialisasi konteks keamanan mungkin memerlukan 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. Meskipun parameter pfContextAttributes valid pada pengembalian yang berhasil, Anda harus memeriksa bendera yang berkaitan dengan aspek keamanan konteks hanya pada pengembalian akhir yang berhasil. 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 . Meskipun ini bukan solusi umum, ini 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 (CredSSP) 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 (CredSSP). 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 (CredSSP) 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 (CredSSP) 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.

Jika fungsi mengembalikan SEC_I_INCOMPLETE_CREDENTIALS, periksa apakah kredensial r yang diteruskan ke fungsi AcquireCredentialsHandle (CredSSP) menentukan sertifikat yang valid dan tepercaya Sertifikat harus menjadi sertifikat autentikasi klien yang dikeluarkan oleh otoritas sertifikasi yang dipercaya oleh server. Untuk mendapatkan daftar CA yang dipercaya oleh server, panggil fungsi QueryContextAttributes (CredSSP) dengan atribut SECPKG_ATTR_ISSUER_LIST_EX .

Setelah menerima sertifikat autentikasi dari otoritas sertifikasi yang dipercaya server, aplikasi klien membuat kredensial baru. Ini dilakukan dengan memanggil fungsi AcquireCredentialsHandle (CredSSP) dan kemudian memanggil InitializeSecurityContext (CredSSP) lagi, menentukan kredensial baru dalam parameter phCredential .

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2008 [hanya aplikasi desktop]
Header Sspi.h (termasuk Security.h)
Pustaka Secur32.lib
DLL Secur32.dll

Lihat juga

Fungsi SSPI

AcceptSecurityContext (CredSSP)

AcquireCredentialsHandle (CredSSP)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc