Fungsi CredUnPackAuthenticationBufferA (wincred.h)

Artikel
08/27/2023

Fungsi CredUnPackAuthenticationBuffer mengonversi buffer autentikasi yang dikembalikan oleh panggilan ke fungsi CredUIPromptForWindowsCredentials menjadi nama pengguna dan kata sandi string.

Sintaks

CREDUIAPI BOOL CredUnPackAuthenticationBufferA(
  [in]      DWORD dwFlags,
  [in]      PVOID pAuthBuffer,
  [in]      DWORD cbAuthBuffer,
  [out]     LPSTR pszUserName,
  [in, out] DWORD *pcchlMaxUserName,
  [out]     LPSTR pszDomainName,
  [in, out] DWORD *pcchMaxDomainName,
  [out]     LPSTR pszPassword,
  [in, out] DWORD *pcchMaxPassword
);

Parameter

[in] dwFlags

Mengatur nilai parameter ini ke CRED_PACK_PROTECTED_CREDENTIALS menentukan bahwa fungsi mencoba mendekripsi kredensial dalam buffer autentikasi. Jika kredensial tidak dapat didekripsi, fungsi mengembalikan FALSE, dan panggilan ke fungsi GetLastError akan mengembalikan nilai ERROR_NOT_CAPABLE.

Bagaimana dekripsi dilakukan tergantung pada format buffer autentikasi.

Jika buffer autentikasi adalah struktur SEC_WINNT_AUTH_IDENTITY_EX2 , fungsi dapat mendekripsi buffer jika dienkripsi dengan menggunakan SspiEncryptAuthIdentityEx dengan opsi SEC_WINNT_AUTH_IDENTITY_ENCRYPT_SAME_LOGON.

Jika buffer autentikasi adalah salah satu struktur KERB_*_LOGON yang terdekripsi, fungsi mendekripsi kata sandi sebelum mengembalikannya di buffer pszPassword .

[in] pAuthBuffer

Penunjuk ke buffer autentikasi yang akan dikonversi.

Buffer ini biasanya merupakan output dari fungsi CredUIPromptForWindowsCredentials atau CredPackAuthenticationBuffer . Ini harus menjadi salah satu jenis berikut:

Struktur SEC_WINNT_AUTH_IDENTITY_EX2 untuk kredensial identitas. Fungsi ini tidak menerima struktur SEC_WINNT_AUTH_IDENTITY lainnya.
Struktur KERB_INTERACTIVE_LOGON atau KERB_INTERACTIVE_UNLOCK_LOGON untuk kredensial kata sandi.
Struktur KERB_CERTIFICATE_LOGON atau KERB_CERTIFICATE_UNLOCK_LOGON untuk kredensial sertifikat kartu pintar.
GENERIC_CRED untuk kredensial generik.

[in] cbAuthBuffer

Ukuran, dalam byte, dari buffer pAuthBuffer .

[out] pszUserName

Penunjuk ke string yang dihentikan null yang menerima nama pengguna.

String ini bisa menjadi kredensial marshal. Lihat Keterangan.

[in, out] pcchlMaxUserName

Penunjuk ke nilai DWORD yang menentukan ukuran, dalam karakter, dari buffer pszUserName . Pada output, jika buffer tidak memiliki ukuran yang memadai, menentukan ukuran yang diperlukan, dalam karakter, dari buffer pszUserName . Ukuran termasuk mengakhiri karakter null.

[out] pszDomainName

Penunjuk ke string yang dihentikan null yang menerima nama domain pengguna.

[in, out] pcchMaxDomainName

Penunjuk ke nilai DWORD yang menentukan ukuran, dalam karakter, dari buffer pszDomainName . Pada output, jika buffer tidak memiliki ukuran yang cukup, menentukan ukuran yang diperlukan, dalam karakter, dari buffer pszDomainName . Ukurannya mencakup karakter null yang mengakhiri. Ukuran yang diperlukan bisa nol jika tidak ada nama domain.

[out] pszPassword

Penunjuk ke string yang dihentikan null yang menerima kata sandi.

[in, out] pcchMaxPassword

Penunjuk ke nilai DWORD yang menentukan ukuran, dalam karakter, dari buffer pszPassword . Pada output, jika buffer tidak memiliki ukuran yang memadai, menentukan ukuran yang diperlukan, dalam karakter, dari buffer pszPassword . Ukurannya mencakup karakter null yang mengakhiri.

String ini bisa menjadi kredensial marshal. Lihat Keterangan.

Mengembalikan nilai

TRUE jika fungsi berhasil; jika tidak, FALSE.

Untuk informasi kesalahan yang diperluas, panggil fungsi GetLastError . Tabel berikut ini memperlihatkan nilai umum untuk fungsi GetLastError .

Mengembalikan kode/nilai	Deskripsi
ERROR_NOT_CAPABLE	CRED_PACK_PROTECTED_CREDENTIALS diteruskan sebagai nilai parameter dwFlags , tetapi fungsi ini tidak dapat mendekripsi kredensial karena konteks keamanan yang digunakan untuk melindungi kata sandi berbeda dari konteks keamanan pemanggil.
ERROR_INSUFFICIENT_BUFFER	Salah satu buffer output, pszUserName, pszDomainName, atau pszPassword, berukuran tidak mencukuum.
ERROR_NOT_SUPPORTED	Buffer autentikasi bukan tipe yang didukung.

Keterangan

Dimulai dengan Windows 8 dan Windows Server 2012, buffer autentikasi dapat menjadi struktur SEC_WINNT_AUTH_IDENTITY_EX2, yang dapat dienkripsi secara opsional dengan menggunakan fungsi SspiEncryptAuthIdentityEx dengan opsi SEC_WINNT_AUTH_IDENTITY_ENCRYPT_SAME_LOGON. Format kredensial ini dikembalikan oleh Penyedia Kredensial Penyedia Identitas dengan menggunakan fungsi CredUIPromptForWindowsCredentials atau SspiPromptForCredentials . Struktur ini juga dapat dibangun dengan menggunakan fungsi CredPackAuthenticationBuffer . Jika buffer autentikasi pAuthBuffer mewakili kredensial nonpassword, seperti KERB_CERTIFICATE_LOGON atau SEC_WINNT_AUTH_IDENTITY_EX2, fungsi harus membasmi kredensial sebagai string karakter, dikembalikan sebagai nama pengguna, nama domain, dan string kata sandi. Marshaling dilakukan dengan menggunakan prosedur tertentu. Ketika dwFlags berisi bendera CRED_PACK_PROTECTED_CREDENTIALS, pemanggil harus berjalan dalam sesi masuk yang sama tempat kredensial dienkripsi.

Catatan

Header wincred.h mendefinisikan CredUnPackAuthenticationBuffer sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta praprosesor 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

Persyaratan	Nilai
Klien minimum yang didukung	Windows Vista [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2008 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincred.h
Pustaka	Credui.lib
DLL	Credui.dll