Fungsi SaslInitializeSecurityContextA (sspi.h)

Artikel
08/26/2023

Fungsi SaslInitializeSecurityContext membungkus panggilan standar ke fungsi Antarmuka Penyedia Dukungan Keamanan InitializeSecurityContext (Umum) dan memproses cookie server SASL dari server.

Sintaks

SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextA(
  [in]            PCredHandle    phCredential,
  [in]            PCtxtHandle    phContext,
  [in]            LPSTR          pszTargetName,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  Reserved1,
  [in]            unsigned long  TargetDataRep,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  Reserved2,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Parameter

[in] phCredential

Handel ke kredensial yang dikembalikan oleh
Fungsi AcquireCredentialsHandle digunakan untuk membangun konteks keamanan. Menggunakan fungsi SaslInitializeSecurityContext memerlukan setidaknya kredensial KELUAR.

[in] phContext

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke fungsi SaslInitializeSecurityContext , 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.

[in] pszTargetName

Penunjuk ke string Unicode atau ANSI yang menunjukkan target konteks.

[in] fContextReq

Bendera bit yang menunjukkan persyaratan konteks. Bendera yang digunakan untuk parameter ini diawali dengan ISC_REQ_; misalnya: ISC_REQ_DELEGATE. Tentukan kombinasi bendera atribut berikut.

Nilai	Makna
ISC_REQ_REPLAY_DETECT	Mendeteksi paket yang diputar ulang.
ISC_REQ_SEQUENCE_DETECT	Mendeteksi pesan yang diterima secara tidak berurutan.
ISC_REQ_CONFIDENTIALITY	Mengenkripsi pesan.
ISC_REQ_STREAM	Mendukung koneksi berorientasi aliran.
ISC_REQ_EXTENDED_ERROR	Ketika terjadi kesalahan, pihak jarak jauh akan diberi tahu.
ISC_REQ_CONNECTION	Konteks keamanan tidak akan menangani pesan pemformatan.
ISC_REQ_MUTUAL_AUTH	Klien dan server akan diautentikasi.
ISC_REQ_INTEGRITY	Menandatangani pesan dan memverifikasi tanda tangan.

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

[in] Reserved1

Nilai yang dipesan; harus nol.

[in] TargetDataRep

Menunjukkan representasi data, seperti pengurutan byte, pada target. Dapat berupa SECURITY_NATIVE_DREP atau SECURITY_NETWORK_DREP.

[in] pInput

Penunjuk ke struktur SecBufferDesc yang berisi pointer ke buffer yang disediakan sebagai input ke paket. Penunjuk harus NULL pada panggilan pertama ke fungsi. Pada panggilan berikutnya ke fungsi, ini adalah penunjuk ke buffer yang dialokasikan dengan memori yang cukup untuk menahan token yang dikembalikan oleh peer jarak jauh.

SASL memerlukan buffer tunggal jenis SECBUFFER_TOKEN yang berisi tantangan yang diterima dari server.

[in] Reserved2

Nilai yang dipesan; harus nol.

[out] phNewContext

Penunjuk ke struktur CtxtHandle . Pada panggilan pertama ke fungsi SaslInitializeSecurityContext , pointer ini menerima handel konteks baru. Pada panggilan kedua, phNewContext dapat sama dengan handel yang ditentukan dalam parameter phContext .

[in, out] pOutput

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

[out] pfContextAttr

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.

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

Nilai kembali

Jika panggilan berhasil diselesaikan, fungsi ini mengembalikan SEC_E_OK. Tabel berikut ini memperlihatkan beberapa kemungkinan nilai pengembalian kegagalan.

Menampilkan kode	Deskripsi
SEC_E_ALGORITHM_MISMATCH	Pemrosesan Authz tidak diizinkan.
SEC_E_INSUFFICIENT_MEMORY	Tidak tersedia cukup memori untuk menyelesaikan permintaan.
SEC_E_INVALID_TOKEN	Tidak ada buffer Token yang terletak di parameter pOutput , atau pesan gagal didekripsi.

Keterangan

Catatan

Header sspi.h mendefinisikan SaslInitializeSecurityContext 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	Tidak ada yang didukung
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