Fungsi AcquireCredentialsHandle (Digest)

Artikel
06/13/2023

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

Saat menggunakan Digest SSP, parameter ini bersifat opsional.

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 (Digest) 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.

fCredentialUse [in]

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

Nilai	Makna
SECPKG_CRED_INBOUND	Memvalidasi kredensial server masuk. Kredensial masuk mungkin divalidasi dengan menggunakan otoritas autentikasi saat InitializeSecurityContext (Digest) atau AcceptSecurityContext (Digest) 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 Digest SSP, parameter ini adalah penunjuk ke struktur SEC_WINNT_AUTH_IDENTITY yang berisi informasi autentikasi yang akan digunakan untuk menemukan kredensial.

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 yang konstan. Tidak ada waktu kedaluwarsa untuk konteks keamananDigest atau kredensial atau saat menggunakan Digest SSP.

Menampilkan 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 (Digest) 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 (Digest) dan InitializeSecurityContext (Digest).

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

Bagikan melalui