Fungsi AcquireCredentialsHandleA (sspi.h)
Fungsi AcquireCredentialsHandle (CredSSP) memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan. Handel ini diperlukan oleh fungsi InitializeSecurityContext (CredSSP) dan AcceptSecurityContext (CredSSP). Ini dapat berupa kredensial yang sudah ada sebelumnya, yang ditetapkan melalui masuk sistem yang tidak dijelaskan di sini, atau pemanggil dapat memberikan kredensial alternatif.
Sintaks
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
[in, optional] LPSTR pszPrincipal,
[in] LPSTR pszPackage,
[in] unsigned long fCredentialUse,
[in, optional] void *pvLogonId,
[in, optional] void *pAuthData,
[in, optional] SEC_GET_KEY_FN pGetKeyFn,
[in, optional] void *pvGetKeyArgument,
[out] PCredHandle phCredential,
[out, optional] PTimeStamp ptsExpiry
);
Parameter
[in, optional] pszPrincipal
Penunjuk ke string yang dihentikan null yang menentukan nama prinsipal yang kredensialnya akan direferensikan oleh handel.
[in] pszPackage
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 (CredSSP) dapat dipanggil dengan ulAttribute diatur ke SECPKG_ATTR_PACKAGE_INFO untuk mengembalikan informasi tentang paket keamanan yang digunakan.
[in] fCredentialUse
Bendera yang menunjukkan bagaimana kredensial ini akan digunakan. Parameter ini bisa menjadi salah satu nilai berikut.
| Nilai | Makna |
|---|---|
|
Memvalidasi kredensial server masuk. Kredensial masuk mungkin divalidasi dengan menggunakan otoritas autentikasi saat InitializeSecurityContext (CredSSP) atau AcceptSecurityContext (CredSSP) dipanggil. Jika otoritas seperti itu tidak tersedia, fungsi akan gagal dan mengembalikan SEC_E_NO_AUTHENTICATING_AUTHORITY. Validasi khusus paket. |
|
Izinkan kredensial klien lokal untuk menyiapkan token keluar. |
[in, optional] pvLogonId
Penunjuk ke pengidentifikasi unik lokal (LUID) yang mengidentifikasi pengguna. Parameter ini disediakan untuk proses sistem file seperti pengalih jaringan. Parameter ini bisa NULL.
[in, optional] pAuthData
Penunjuk ke struktur CREDSSP_CRED yang menentukan data autentikasi untuk paket Schannel dan Negosiasi.
[in, optional] pGetKeyFn
Dicadangkan. Parameter ini tidak digunakan dan harus diatur ke NULL.
[in, optional] pvGetKeyArgument
Dicadangkan. Parameter ini harus diatur ke NULL.
[out] phCredential
Penunjuk ke struktur CredHandle yang akan menerima handel kredensial.
[out, optional] ptsExpiry
Penunjuk ke struktur TimeStamp yang menerima waktu kedaluwarsa kredensial yang dikembalikan. Nilai struktur yang diterima tergantung pada paket keamanan, yang harus menentukan nilai dalam waktu lokal.
Nilai kembali
Jika fungsi berhasil, fungsi akan mengembalikan SEC_E_OK.
Jika fungsi gagal, fungsi 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 galat SSPI. |
|
Tidak ada kredensial yang tersedia dalam paket keamanan. |
|
Pemanggil fungsi tidak memiliki kredensial yang diperlukan. |
|
Paket keamanan yang diminta tidak ada. |
|
Kredensial yang diberikan ke paket tidak dikenali. |
Keterangan
Fungsi AcquireCredentialsHandle (CredSSP) mengembalikan handel ke kredensial prinsipal, seperti pengguna atau klien, seperti yang digunakan oleh paket keamanan tertentu. Fungsi ini dapat mengembalikan handel ke kredensial yang sudah ada sebelumnya atau kredensial yang baru dibuat dan mengembalikannya. Handel ini dapat digunakan dalam panggilan berikutnya ke fungsi AcceptSecurityContext (CredSSP) dan InitializeSecurityContext (CredSSP).
Secara umum, AcquireCredentialsHandle (CredSSP) tidak memberikan kredensial pengguna lain yang masuk ke komputer yang sama. Namun, penelepon dengan hak istimewa SE_TCB_NAME dapat memperoleh kredensial sesi masuk yang ada dengan menentukan pengidentifikasi masuk (LUID) dari 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.
Catatan
Header sspi.h mendefinisikan AcquireCredentialsHandle sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosedur 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
| Klien minimum yang didukung | Windows Vista [hanya aplikasi desktop] |
| Server minimum yang didukung | Windows Server 2008 [hanya aplikasi desktop] |
| Target Platform | Windows |
| Header | sspi.h (termasuk Security.h) |
| Pustaka | Secur32.lib |
| DLL | Secur32.dll |
Lihat juga
AcceptSecurityContext (CredSSP)
Saran dan Komentar
Segera hadir: Sepanjang tahun 2024 kami akan menghentikan penggunaan GitHub Issues sebagai mekanisme umpan balik untuk konten dan menggantinya dengan sistem umpan balik baru. Untuk mengetahui informasi selengkapnya, lihat: https://aka.ms/ContentUserFeedback.
Kirim dan lihat umpan balik untuk