Fungsi AcquireCredentialsHandle (Negosiasi)

Artikel
06/13/2023

Fungsi AcquireCredentialsHandle (Negosiasi) memperoleh handel untuk kredensial yang sudah ada sebelumnya dari prinsip keamanan. Handel ini diperlukan oleh fungsi InitializeSecurityContext (Negosiasi) dan AcceptSecurityContext (Negosiasi). Ini dapat berupa kredensial yang sudah ada sebelumnya, yang ditetapkan melalui masuk sistem yang tidak dijelaskan di sini, atau pemanggil 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 prinsipal 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 (Negosiasi) dapat dipanggil dengan ulAttribute diatur ke SECPKG_ATTR_PACKAGE_INFO untuk mengembalikan informasi tentang paket keamanan yang digunakan.

Agar berhasil memanggil fungsi ini menggunakan Negosiasi SSP, atur parameter ini ke "Negosiasi".

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. 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.
SECPKG_CRED_INBOUND	Memvalidasi kredensial server masuk. Kredensial masuk mungkin divalidasi dengan menggunakan otoritas autentikasi saat InitializeSecurityContext (Negosiasi) atau AcceptSecurityContext (Negosiasi) 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. 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.

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, teruskan struktur PSEC_WINNT_AUTH_IDENTITY_OPAQUE yang dikembalikan dari panggilan sebelumnya ke fungsi SspiPromptForCredentials .

Windows Server 2008, Windows Vista, Windows Server 2003 dan Windows XP: Jenis PSEC_WINNT_AUTH_IDENTITY_OPAQUE dan fungsi SspiPromptForCredentials tidak didukung. Untuk menggunakan kredensial yang disediakan, berikan penunjuk ke struktur SEC_WINNT_AUTH_IDENTITY atau SEC_WINNT_AUTH_IDENTITY_EX yang menyertakan kredensial tersebut.

Run time RPC melewati apa pun yang disediakan di RpcBindingSetAuthInfo.

Saat menggunakan paket 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.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan SEC_E_OK.

Jika fungsi gagal, fungsi 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 (Negosiasi) 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 (Negosiasi) dan InitializeSecurityContext (Negosiasi).

Secara umum, AcquireCredentialsHandle (Negosiasi) 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 (Negosiasi)
InitializeSecurityContext (Negosiasi)
FreeCredentialsHandle

Bagikan melalui