Fungsi AcquireCredentialsHandle (NTLM)
Fungsi AcquireCredentialsHandle (NTLM) memperoleh handel untuk kredensial yang sudah ada sebelumnya dari prinsip keamanan. Handel ini diperlukan oleh fungsi InitializeSecurityContext (NTLM) dan AcceptSecurityContext (NTLM). Ini bisa berupa kredensial yang sudah ada sebelumnya, yang ditetapkan melalui masuk sistem yang tidak dijelaskan di sini, atau penelepon dapat memberikan kredensial alternatif.
Catatan
Ini bukan "masuk ke jaringan" dan tidak menyiratkan pengumpulan kredensial.
Sintaks
SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
_In_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_ PLUID pvLogonID,
_In_ PVOID pAuthData,
_In_ SEC_GET_KEY_FN pGetKeyFn,
_In_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_ PTimeStamp ptsExpiry
);
Parameter
-
pszPrincipal [in]
-
Penunjuk ke string yang dihentikan null yang menentukan nama utama yang kredensialnya akan direferensikan oleh handel.
Catatan
Jika proses yang meminta handel tidak memiliki akses ke kredensial, fungsi mengembalikan kesalahan. String null menunjukkan bahwa proses memerlukan handel ke kredensial pengguna di bawah konteks keamanan yang dijalankannya.
-
pszPackage [in]
-
Penunjuk ke string yang dihentikan null yang menentukan nama paket keamanan tempat kredensial ini akan digunakan. Ini adalah nama paket keamanan yang dikembalikan dalam anggota Nama struktur SecPkgInfo yang dikembalikan oleh fungsi EnumerateSecurityPackages . Setelah konteks ditetapkan, QueryContextAttributes (NTLM) dapat dipanggil dengan ulAttribute diatur ke SECPKG_ATTR_PACKAGE_INFO untuk mengembalikan informasi tentang paket keamanan yang digunakan.
-
fCredentialUse [in]
-
Bendera yang menunjukkan bagaimana kredensial ini akan digunakan. Parameter ini bisa menjadi salah satu nilai berikut.
Nilai Makna - SECPKG_CRED_BOTH
Validasi kredensial masuk atau gunakan kredensial lokal untuk menyiapkan token keluar. Bendera ini memungkinkan kedua bendera lainnya. - SECPKG_CRED_INBOUND
Validasi kredensial server masuk. Kredensial masuk mungkin divalidasi dengan menggunakan otoritas autentikasi saat InitializeSecurityContext (NTLM) atau AcceptSecurityContext (NTLM) dipanggil. Jika otoritas seperti itu tidak tersedia, fungsi akan gagal dan mengembalikan SEC_E_NO_AUTHENTICATING_AUTHORITY. Validasi khusus paket. - SECPKG_CRED_OUTBOUND
Izinkan kredensial klien lokal untuk menyiapkan token keluar. -
pvLogonID [in]
-
Penunjuk ke pengidentifikasi unik lokal (LUID) yang mengidentifikasi pengguna. Parameter ini disediakan untuk proses sistem file seperti pengalih jaringan. Parameter ini bisa NULL.
-
pAuthData [in]
-
Penunjuk ke data khusus paket. Parameter ini dapat berupa NULL, yang menunjukkan bahwa kredensial default untuk paket keamanan tersebut harus digunakan. Untuk menggunakan kredensial yang disediakan, berikan struktur SEC_WINNT_AUTH_IDENTITY yang menyertakan kredensial tersebut dalam parameter ini. Run time RPC melewati apa pun yang disediakan di RpcBindingSetAuthInfo.
Saat menggunakan paket NTLM, panjang karakter maksimum untuk nama pengguna, kata sandi, dan domain masing-masing adalah 256, 256, dan 15.
-
pGetKeyFn [in]
-
Parameter ini tidak digunakan dan harus diatur ke NULL.
-
pvGetKeyArgument [in]
-
Parameter ini tidak digunakan dan harus diatur ke NULL.
-
phCredential [out]
-
Penunjuk ke struktur CredHandle untuk menerima handel kredensial.
-
ptsExpiry [out]
-
Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa kredensial yang dikembalikan. Nilai yang dikembalikan dalam struktur TimeStamp ini tergantung pada delegasi yang dibatasi. Paket keamanan harus mengembalikan nilai ini dalam waktu lokal.
Menampilkan nilai
Jika fungsi berhasil, fungsi akan mengembalikan SEC_E_OK.
Jika fungsi gagal, fungsi akan 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. |
|
Tidak ada kredensial yang tersedia dalam delegasi yang dibatasi. |
|
Pemanggil fungsi tidak memiliki kredensial yang diperlukan. |
|
Paket keamanan yang diminta tidak ada. |
|
Kredensial yang diberikan ke paket tidak dikenali. |
Keterangan
Fungsi AcquireCredentialsHandle (NTLM) mengembalikan handel ke kredensial utama, seperti pengguna atau klien, seperti yang digunakan oleh delegasi tertentu yang dibatasi. Ini bisa menjadi handel untuk kredensial yang sudah ada sebelumnya, atau fungsi dapat membuat sekumpulan kredensial baru dan mengembalikannya. Handel ini dapat digunakan dalam panggilan berikutnya ke fungsi AcceptSecurityContext (NTLM) dan InitializeSecurityContext (NTLM).
Secara umum, AcquireCredentialsHandle (NTLM) tidak mengizinkan proses untuk mendapatkan handel ke kredensial pengguna lain yang masuk ke komputer yang sama. Namun, penelepon dengan hak istimewa SE_TCB_NAME memiliki opsi untuk menentukan pengidentifikasi masuk (LUID) dari token sesi masuk yang ada untuk mendapatkan handel ke kredensial sesi tersebut. Biasanya, ini digunakan oleh modul mode kernel yang harus bertindak atas nama pengguna yang masuk.
Paket mungkin memanggil fungsi di pGetKeyFn yang disediakan oleh transportasi run-time RPC. Jika transportasi tidak mendukung gagasan panggilan balik untuk mengambil kredensial, parameter ini harus NULL.
Untuk pemanggil mode kernel, perbedaan berikut harus dicatat:
- Dua parameter string harus string Unicode .
- Nilai buffer harus dialokasikan dalam memori virtual proses, bukan dari kumpulan.
Setelah Anda selesai menggunakan kredensial yang dikembalikan, bebaskan memori yang digunakan oleh kredensial dengan memanggil fungsi FreeCredentialsHandle .
Persyaratan
| Persyaratan | Nilai |
|---|---|
| Klien minimum yang didukung |
Windows XP [hanya aplikasi desktop] |
| Server minimum yang didukung |
Windows Server 2003 [hanya aplikasi desktop] |
| Header |
|
| Pustaka |
|
| DLL |
|
| Nama Unicode dan ANSI |
AcquireCredentialsHandleW (Unicode) dan AcquireCredentialsHandleA (ANSI) |
Lihat juga