LSA_AP_LOGON_USER_EX fungsi panggilan balik (ntsecpkg.h)

Artikel
08/25/2023

Mengautentikasi kredensial masuk pengguna.

Fungsi ini dipanggil oleh Otoritas Keamanan Lokal (LSA) hanya untuk masuk awal pengguna. Permintaan autentikasi berikutnya harus menggunakan LsaCallAuthenticationPackage. Jika LsaApLogonUserEx berhasil, LsaApLogonUserEx membuat sesi masuk dan mengembalikan informasi yang digunakan untuk membangun token yang mewakili pengguna yang baru masuk.

Fungsi ini berbeda dari LsaApLogonUser karena nama komputer ditambahkan ke catatan audit untuk upaya masuk.

Sintaks

LSA_AP_LOGON_USER_EX LsaApLogonUserEx;

NTSTATUS LsaApLogonUserEx(
  [in]  PLSA_CLIENT_REQUEST ClientRequest,
  [in]  SECURITY_LOGON_TYPE LogonType,
  [in]  PVOID AuthenticationInformation,
  [in]  PVOID ClientAuthenticationBase,
  [in]  ULONG AuthenticationInformationLength,
  [out] PVOID *ProfileBuffer,
  [out] PULONG ProfileBufferLength,
  [out] PLUID LogonId,
  [out] PNTSTATUS SubStatus,
  [out] PLSA_TOKEN_INFORMATION_TYPE TokenInformationType,
  [out] PVOID *TokenInformation,
  [out] PUNICODE_STRING *AccountName,
  [out] PUNICODE_STRING *AuthenticatingAuthority,
  [out] PUNICODE_STRING *MachineName
)
{...}

Parameter

[in] ClientRequest

Penunjuk ke jenis data LSA_CLIENT_REQUEST buram yang mewakili permintaan klien LSA.

[in] LogonType

Struktur SECURITY_LOGON_TYPE yang mengidentifikasi jenis masuk yang sedang dicoba.

[in] AuthenticationInformation

Menyediakan informasi autentikasi khusus untuk paket autentikasi. LSA akan membebaskan buffer ini.

[in] ClientAuthenticationBase

Menyediakan alamat informasi autentikasi dalam proses klien. Ini mungkin diperlukan untuk memetakan ulang penunjuk apa pun dalam buffer AuthenticationInformation .

[in] AuthenticationInformationLength

Menunjukkan panjang buffer AuthenticationInformation .

[out] ProfileBuffer

Pointer yang menerima alamat buffer profil dalam proses klien. Paket autentikasi bertanggung jawab untuk mengalokasikan buffer ProfileBuffer dalam proses klien dengan memanggil fungsi AllocateClientBuffer . Namun, jika LSA kemudian mengalami kesalahan yang mencegah keberhasilan masuk, maka LSA akan mengurus pemberhentian buffer ini.

Isi buffer ini ditentukan oleh paket autentikasi. LSA tidak mengubah buffer ini; itu hanya mengembalikan nilai ke fungsi LsaLogonUser .

[out] ProfileBufferLength

Penunjuk ke ULONG yang menerima panjang buffer ProfileBuffer , dalam byte.

[out] LogonId

Penunjuk ke variabel LUID yang menerima ID masuk baru yang secara unik mengidentifikasi sesi masuk ini. Paket autentikasi bertanggung jawab untuk mengalokasikan LUID ini dan membuat sesi masuk LSA untuk masuk ini.

[out] SubStatus

Arahkan ke NTSTATUS yang menerima alasan kegagalan karena pembatasan akun. Nilai yang dikembalikan dalam SubStatus ditentukan oleh paket autentikasi.

Berikut ini adalah nilai SubStatus untuk paket autentikasi MSV1_0 dan Kerberos.

Nilai	Makna
STATUS_INVALID_LOGON_HOURS	Akun pengguna memiliki batasan waktu dan tidak dapat digunakan untuk masuk saat ini.
STATUS_INVALID_WORKSTATION	Akun pengguna memiliki batasan stasiun kerja dan tidak dapat digunakan untuk masuk dari stasiun kerja saat ini.
STATUS_PASSWORD_EXPIRED	Kata sandi akun pengguna telah kedaluwarsa.
STATUS_ACCOUNT_DISABLED	Akun pengguna saat ini dinonaktifkan dan tidak dapat digunakan untuk masuk.

Informasi selengkapnya tentang kode NTSTATUS dapat ditemukan di file header Subauth.h yang dikirim dengan Platform SDK.

[out] TokenInformationType

Pointer yang menerima alamat nilai LSA_TOKEN_INFORMATION_TYPE yang menunjukkan jenis informasi yang dikembalikan untuk dimasukkan dalam token yang akan dibuat. Informasi dikembalikan dengan parameter TokenInformation .

[out] TokenInformation

Pointer yang menerima alamat informasi yang akan disertakan dalam token. Format dan konten TokenInformation ditunjukkan oleh parameter TokenInformationType . Paket autentikasi Anda bertanggung jawab untuk mengalokasikan memori yang digunakan oleh TokenInformation; namun, memori ini akan dikosongkan oleh LSA.

[out] AccountName

Arahkan ke struktur LSA_UNICODE_STRING yang menerima nama akun pengguna. AccountName harus selalu dikembalikan terlepas dari keberhasilan atau kegagalan panggilan; string-nya disertakan dalam catatan audit untuk upaya autentikasi. Paket autentikasi Anda bertanggung jawab untuk mengalokasikan memori yang digunakan oleh AccountName Ini akan dikosongkan oleh LSA.

[out] AuthenticatingAuthority

Opsional. Arahkan ke struktur LSA_UNICODE_STRING yang menerima deskripsi otoritas autentikasi untuk masuk. Parameter ini mungkin NULL. String ini disertakan dalam catatan audit untuk upaya autentikasi. Paket autentikasi Anda bertanggung jawab untuk mengalokasikan memori yang digunakan oleh AuthenticatingAuthority; namun, memori ini akan dikosongkan oleh LSA.

Paket autentikasi MSV1_0 mengembalikan nama domain domain yang memvalidasi akun. Paket autentikasi Kerberos mengembalikan nama domain NetBIOS.

[out] MachineName

Opsional. Pointer yang menerima alamat struktur LSA_UNICODE_STRING yang berisi nama stasiun kerja klien. Informasi ini disertakan dalam catatan audit untuk upaya autentikasi. Paket autentikasi Anda bertanggung jawab untuk mengalokasikan memori yang digunakan oleh MachineName; namun, memori ini akan dikosongkan oleh LSA.

Paket autentikasi MSV1_0 mengembalikan nama NetBIOS dari stasiun kerja klien.

Mengembalikan nilai

Jika fungsi berhasil, fungsi harus mengembalikan STATUS_SUCCESS.

Jika tidak, kode kesalahan harus mengembalikan kode kesalahan NTSTATUS, yang dapat menjadi salah satu nilai berikut atau salah satu Nilai Pengembalian Fungsi Kebijakan LSA.

Menampilkan kode	Deskripsi
STATUS_NO_MEMORY	Log masuk tidak dapat diselesaikan karena kuota memori klien tidak cukup untuk mengalokasikan buffer pengembalian.
STATUS_NO_LOGON_SERVERS	Tidak ada pengendali domain yang tersedia untuk melayani permintaan autentikasi.
STATUS_LOGON_FAILURE	Upaya masuk gagal. Alasan kegagalan tidak ditentukan; alasan umum termasuk nama pengguna dan kata sandi yang salah eja.
STATUS_ACCOUNT_RESTRICTION	Akun pengguna dan kata sandi sah, tetapi pembatasan akun pengguna mencegah keberhasilan masuk saat ini.
STATUS_BAD_VALIDATION_CLASS	Informasi autentikasi yang diberikan dikenali oleh paket autentikasi.

Aplikasi panggilan dapat menggunakan fungsi LsaNtStatusToWinError untuk mengonversi kode NTSTATUS ke kode kesalahan Windows.

Keterangan

Paket autentikasi harus menerapkan salah satu fungsi berikut: LsaApLogonUser, LsaApLogonUserEx, atau LsaApLogonUserEx2.

LsaApLogonUserEx ditambahkan untuk sertifikasi C2. C2 adalah klasifikasi keamanan yang ditentukan oleh pemerintah Amerika Serikat.

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