Fungsi AcquireCredentialsHandle (Umum)

Artikel
06/13/2023

Fungsi AcquireCredentialsHandle (Umum) memperoleh handel untuk kredensial yang sudah ada sebelumnya dari prinsip keamanan. Handel ini diperlukan oleh fungsi InitializeSecurityContext (Umum) dan AcceptSecurityContext (Umum). 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.

Untuk informasi tentang menggunakan fungsi ini dengan penyedia dukungan keamanan (SSP) tertentu, lihat topik berikut.

Topik	Deskripsi
AcquireCredentialsHandle (CredSSP)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan Penyedia Dukungan Keamanan Kredensial (CredSSP).
AcquireCredentialsHandle (Digest)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan Digest.
AcquireCredentialsHandle (Kerberos)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan Kerberos.
AcquireCredentialsHandle (Negosiasi)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan Negosiasi.
AcquireCredentialsHandle (NTLM)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan NTLM.
AcquireCredentialsHandle (Schannel)	Memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan yang menggunakan Schannel.

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.

Saat menggunakan Digest SSP, parameter ini bersifat opsional.

Saat menggunakan Schannel SSP, parameter ini tidak digunakan dan harus diatur ke NULL.

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 (Umum) dapat dipanggil dengan ulAttribute diatur ke SECPKG_ATTR_PACKAGE_INFO untuk mengembalikan informasi tentang paket keamanan yang digunakan.

Saat menggunakan Digest SSP, atur parameter ini ke WDIGEST_SP_NAME.

Saat menggunakan Schannel SSP, atur parameter ini ke UNISP_NAME.

fCredentialUse [in]

Bendera yang menunjukkan bagaimana kredensial ini akan digunakan. Parameter ini bisa menjadi salah satu nilai berikut.

Nilai	Makna
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	Keamanan tidak menggunakan kredensial log masuk default atau kredensial dari Pengelola Kredensial. Nilai ini hanya didukung oleh delegasi yang dibatasi Negosiasi. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.
SECPKG_CRED_BOTH	Validasi kredensial masuk atau gunakan kredensial lokal untuk menyiapkan token keluar. Bendera ini memungkinkan kedua bendera lainnya. Bendera ini tidak valid dengan SSP Digest dan Schannel.
SECPKG_CRED_INBOUND	Validasi kredensial server masuk. Kredensial masuk mungkin divalidasi dengan menggunakan otoritas autentikasi saat InitializeSecurityContext (Umum) atau AcceptSecurityContext (Umum) 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.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	Fungsi ini memproses kebijakan server dan mengembalikan SEC_E_NO_CREDENTIALS, menunjukkan bahwa aplikasi harus meminta kredensial. Nilai ini hanya didukung oleh delegasi yang dibatasi Negosiasi. Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Nilai ini tidak didukung.

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.

Saat menggunakan Schannel SSP, parameter ini tidak digunakan dan harus diatur ke 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 Digest SSP, parameter ini adalah penunjuk ke struktur SEC_WINNT_AUTH_IDENTITY yang berisi informasi autentikasi untuk digunakan untuk menemukan kredensial.

Saat menggunakan Schannel SSP, tentukan struktur SCHANNEL_CRED yang menunjukkan protokol yang akan digunakan dan pengaturan untuk berbagai fitur saluran yang dapat disesuaikan.

Saat menggunakan paket NTLM atau Negosiasi, 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.

Parameter ini diatur ke waktu maksimum konstanta. Tidak ada waktu kedaluwarsa untuk konteks keamananDigest atau kredensial atau saat menggunakan Digest SSP.

Saat menggunakan Schannel SSP, parameter ini bersifat opsional. Ketika kredensial yang akan digunakan untuk autentikasi adalah sertifikat, parameter ini menerima waktu kedaluwarsa untuk sertifikat tersebut. Jika tidak ada sertifikat yang disediakan, maka nilai waktu maksimum dikembalikan.

Nilai kembali

Jika fungsi berhasil, fungsi akan mengembalikan SEC_E_OK.

Jika fungsi gagal, fungsi akan 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 galat SSPI.
SEC_E_NO_CREDENTIALS	Tidak ada kredensial yang tersedia dalam delegasi yang dibatasi.
SEC_E_NOT_OWNER	Pemanggil fungsi tidak memiliki kredensial yang diperlukan.
SEC_E_SECPKG_NOT_FOUND	Paket keamanan yang diminta tidak ada.
SEC_E_UNKNOWN_CREDENTIALS	Kredensial yang diberikan ke paket tidak dikenali.

Keterangan

Fungsi AcquireCredentialsHandle (Umum) mengembalikan handel ke kredensial prinsipal, seperti pengguna atau klien, seperti yang digunakan oleh delegasi tertentu yang dibatasi. Ini bisa menjadi pegangan 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 (Umum) dan InitializeSecurityContext (Umum).

Secara umum, AcquireCredentialsHandle (Umum) 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, kosongkan 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	Sspi.h (termasuk Security.h)
Pustaka	Secur32.lib
DLL	Secur32.dll
Nama Unicode dan ANSI	AcquireCredentialsHandleW (Unicode) dan AcquireCredentialsHandleA (ANSI)

Lihat juga

Fungsi SSPI
AcceptSecurityContext (Umum)
InitializeSecurityContext (Umum)
FreeCredentialsHandle

Bagikan melalui