Fungsi AcquireCredentialsHandle (Schannel)
Fungsi AcquireCredentialsHandle (Schannel) memperoleh handel ke kredensial yang sudah ada sebelumnya dari prinsip keamanan. Handel ini diperlukan oleh fungsi InitializeSecurityContext (Schannel) dan AcceptSecurityContext (Schannel). 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_opt_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_opt_ PLUID pvLogonID,
_In_opt_ PVOID pAuthData,
_In_opt_ SEC_GET_KEY_FN pGetKeyFn,
_In_opt_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_opt_ PTimeStamp ptsExpiry
);
Parameter
pszPrincipal[in, optional]
Penunjuk ke string yang dihentikan null yang menentukan nama prinsipal yang kredensialnya akan direferensikan oleh handel.
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 (Schannel) dapat dipanggil dengan ulAttribute diatur ke SECPKG_ATTR_PACKAGE_INFO untuk mengembalikan informasi tentang paket keamanan yang digunakan.
Saat menggunakan Schannel SSP, atur parameter ini ke UNISP_NAME.
Catatan
Pemanggil mode kernel yang mengalami masalah saat memanggil InitializeSecurityContext (Schannel) setelah memanggil AcquireCredentialsHandle (Schannel) dapat mengatur pszPackage ke SCHANNEL_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 (Schannel) atau AcceptSecurityContext (Schannel) 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, optional]
Penunjuk ke pengidentifikasi unik lokal (LUID) yang mengidentifikasi pengguna. Parameter ini disediakan untuk proses sistem file seperti pengalih jaringan. Parameter ini dapat berupa NULL.
Saat menggunakan Schannel SSP, parameter ini tidak digunakan dan harus diatur ke NULL.
pAuthData[in, optional]
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 Schannel SSP, tentukan struktur SCH_CREDENTIALS yang menunjukkan protokol yang akan digunakan dan pengaturan untuk berbagai fitur saluran yang dapat disesuaikan.
pGetKeyFn[in, optional]
Parameter ini tidak digunakan dan harus diatur ke NULL.
pvGetKeyArgument[in, optional]
Parameter ini tidak digunakan dan harus diatur ke NULL.
phCredential[out]
Penunjuk ke struktur CredHandle untuk menerima handel kredensial.
ptsExpiry[out, optional]
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.
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 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 (Schannel) 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 (Schannel) dan InitializeSecurityContext (Schannel).
Secara umum, AcquireCredentialsHandle (Schannel) tidak mengizinkan proses untuk mendapatkan handel ke kredensial pengguna lain yang masuk ke komputer yang sama. Namun, penelepon dengan hak istimewaSE_TCB_NAME memiliki opsi untuk menentukan pengidentifikasi masuk (LUID) dari token sesi masuk yang ada untuk mendapatkan penanganan 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
AcceptSecurityContext (Schannel)