Fungsi CredUICmdLinePromptForCredentialsA (wincred.h)

Artikel
08/27/2023

Fungsi CredUICmdLinePromptForCredentials meminta dan menerima informasi kredensial dari pengguna yang bekerja di aplikasi baris perintah (konsol). Nama dan kata sandi yang di ketik oleh pengguna diteruskan kembali ke aplikasi panggilan untuk verifikasi.

Sintaks

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

Parameter

[in] pszTargetName

Penunjuk ke string yang dihentikan null yang berisi nama target untuk kredensial, biasanya nama server. Untuk koneksi DFS, string ini adalah dari formulir ServerName\ShareName. Parameter pszTargetName digunakan untuk mengidentifikasi informasi target dan digunakan untuk menyimpan dan mengambil kredensial.

[in] pContext

Saat ini dicadangkan dan harus NULL.

[in, optional] dwAuthError

Menentukan mengapa meminta kredensial diperlukan. Pemanggil dapat meneruskan parameter kesalahan Windows ini, dikembalikan oleh panggilan autentikasi lain, untuk memungkinkan kotak dialog mengakomodasi kesalahan tertentu. Misalnya, jika kode status kedaluwarsa kata sandi diteruskan, kotak dialog meminta pengguna untuk mengubah kata sandi pada akun.

[in, out] UserName

Penunjuk ke string yang dihentikan null yang berisi nama pengguna kredensial. Jika string panjang bukan nol ditentukan untuk pszUserName, pengguna hanya akan dimintai kata sandi. Dalam kasus kredensial selain nama pengguna/kata sandi, format marshaled kredensial dapat diteruskan. String ini dibuat dengan memanggil CredMarshalCredential.

Fungsi ini menulis nama yang disediakan pengguna ke buffer ini, menyalin maksimum karakter ulUserNameMaxChars . String dalam format ini dapat dikonversi ke format nama pengguna/kata sandi dengan memanggil fungsi CredUIParseUsername . String dalam format marshaled-nya dapat diteruskan langsung ke penyedia dukungan keamanan (SSP).

Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST tidak ditentukan, nilai yang dikembalikan dalam parameter ini adalah formulir yang tidak boleh diperiksa, dicetak, atau disimpan selain meneruskannya ke CredUIParseUsername. Hasil credUIParseUsername berikutnya hanya dapat diteruskan ke API autentikasi sisi klien seperti WNetAddConnection atau API SSP.

[in] ulUserBufferSize

Jumlah maksimum karakter yang dapat disalin ke pszUserName termasuk karakter null yang mengakhiri.

Catatan CREDUI_MAX_USERNAME_LENGTH tidak menyertakan karakter null yang mengakhiri.

[in, out] pszPassword

Penunjuk ke string yang dihentikan null yang berisi kata sandi untuk kredensial. Jika string panjang bukan nol ditentukan untuk pszPassword, parameter kata sandi akan diisi sebelumnya dengan string.

Fungsi ini menulis kata sandi yang disediakan pengguna ke buffer ini, menyalin maksimum karakter ulPasswordMaxChars . Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST tidak ditentukan, nilai yang dikembalikan dalam parameter ini adalah formulir yang tidak boleh diperiksa, dicetak, atau disimpan selain meneruskannya ke fungsi autentikasi sisi klien seperti WNetAddConnection atau fungsi SSP.

Setelah Anda selesai menggunakan kata sandi, hapus kata sandi dari memori dengan memanggil fungsi SecureZeroMemory . Untuk informasi selengkapnya tentang melindungi kata sandi, lihat Menangani Kata Sandi.

[in] ulPasswordBufferSize

Jumlah maksimum karakter yang dapat disalin ke pszPassword termasuk karakter null yang mengakhiri.

Catatan CREDUI_MAX_PASSWORD_LENGTH tidak menyertakan karakter null yang mengakhiri.

[in, out] pfSave

Penunjuk ke BOOL yang menentukan status awal pesan Simpan dan menerima status Simpan pesan setelah pengguna merespons perintah. Jika pfSave bukan NULL dan CredUIPromptForCredentials mengembalikan NO_ERROR, pfSave mengembalikan status Simpan pesan. Jika bendera CREDUI_FLAGS_PERSIST ditentukan, pesan Simpan tidak ditampilkan tetapi dianggap "y". Jika bendera CREDUI_FLAGS_DO_NOT_PERSIST ditentukan dan CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX tidak ditentukan, pesan Simpan tidak ditampilkan tetapi dianggap "n".

[in] dwFlags

Nilai DWORD yang menentukan perilaku khusus untuk fungsi ini. Nilai ini bisa berupa kombinasi bitwise-OR dari nol atau lebih dari nilai berikut.

Nilai	Makna
CREDUI_FLAGS_ALWAYS_SHOW_UI	Tampilkan antarmuka pengguna jika kredensial dapat dikembalikan dari kredensial yang ada di pengelola kredensial. Bendera ini hanya diizinkan jika CREDUI_FLAGS_GENERIC_CREDENTIALS juga ditentukan dan hanya digunakan bersama dengan CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_DO_NOT_PERSIST	Jangan tampilkan pesan simpan atau simpan kredensial. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX juga dapat diteruskan untuk menampilkan pesan simpan saja dan mengembalikan hasilnya di pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Minta nama pengguna/kata sandi. Jika parameter pszUserName ditentukan, nama pengguna akan dihilangkan. Jika kredensial tetap ada, simpan nama pengguna yang diteruskan dengan kredensial.
CREDUI_FLAGS_EXPECT_CONFIRMATION	Menentukan bahwa pemanggil akan memanggil CredUIConfirmCredentials untuk menentukan apakah kredensial yang dikembalikan benar-benar valid. Ini memastikan bahwa kredensial yang tidak valid tidak disimpan ke manajer kredensial. Tentukan bendera ini kecuali CREDUI_FLAGS_DO_NOT_PERSIST ditentukan.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Pertimbangkan kredensial yang dimasukkan oleh pengguna kredensial generik.
CREDUI_FLAGS_INCORRECT_PASSWORD	Abaikan bendera ini secara diam-diam.
CREDUI_FLAGS_PERSIST	Jangan tampilkan pesan simpan, tetapi simpan kredensial seolah-olah pengguna menjawab "y".
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Abaikan bendera ini secara diam-diam.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Dicadangkan untuk digunakan di masa mendatang; jangan berikan bendera ini.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Gunakan kartu pintar dan minta PIN. Jika tersedia lebih dari satu kartu pintar, pilih salah satunya. Jika parameter pszUserName melewati string yang tidak kosong, string harus cocok dengan UPN yang terkait dengan sertifikat pada salah satu kartu pintar. UPN cocok jika string cocok dengan seluruh UPN pada sertifikat atau string cocok dengan bagian di sebelah kiri tanda (@) di UPN sertifikat. Jika ada kecocokan, kartu pintar yang cocok dipilih.
CREDUI_FLAGS_SERVER_CREDENTIAL	Bendera ini bermakna hanya dalam menemukan kredensial yang cocok untuk mengisi kotak dialog terlebih dahulu, jika autentikasi gagal. Ketika bendera ini ditentukan, kredensial kartubebas tidak akan dicocokkan. Ini tidak berpengaruh saat menulis kredensial. CredUI tidak membuat kredensial yang berisi karakter kartubebas. Setiap yang ditemukan dibuat secara eksplisit oleh pengguna atau dibuat secara terprogram, seperti yang terjadi ketika koneksi RAS dibuat.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Tampilkan pesan simpan dan kembalikan TRUE di parameter pfSave out jika pengguna menjawab "y", FALSE jika pengguna menjawab "n". CREDUI_FLAGS_DO_NOT_PERSIST harus ditentukan untuk menggunakan bendera ini.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Kredensial adalah kredensial run-as. Parameter pszTargetName menentukan nama perintah atau program yang sedang dijalankan. Ini hanya digunakan untuk meminta tujuan.

Nilai kembali

Nilai yang dikembalikan adalah DWORD dan bisa menjadi salah satu nilai berikut.

Nilai	Deskripsi
ERROR_INVALID_FLAGS	Status ini dikembalikan untuk salah satu kombinasi bendera yang tidak valid.
ERROR_INVALID_PARAMETER	PszTargetName adalah NULL, string kosong, atau lebih panjang dari CREDUI_MAX_DOMAIN_LENGTH, atau pUiInfo tidak NULL dan struktur CredUI_INFO yang ditujukan untuk tidak memenuhi salah satu persyaratan berikut: Anggota cbSize harus satu. Jika anggota hbmBanner bukan NULL, harus berjenis OBJ_BITMAP. Jika anggota pszMessageText bukan NULL, anggota pszMessageText tidak boleh lebih besar dari CREDUI_MAX_MESSAGE_LENGTH. Jika anggota pszCaptionText bukan NULL, anggota pszCaptionText tidak boleh lebih besar dari CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION	Manajer kredensial tidak dapat digunakan. Biasanya, kesalahan ini ditangani dengan memanggil CredUICmdLinePromptForCredentials dan meneruskan bendera CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	Pengguna memilih OK. Variabel pszUserName, pszPassword, dan pfSave akan mengembalikan nilai yang didokumenkan sebelumnya.

Keterangan

Bendera CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE, dan CREDUI_FLAGS_EXCLUDE_CERTIFICATE saling eksklusif.

Jika CREDUI_FLAGS_DO_NOT_PERSIST ditentukan, pszTargetName harus ditentukan atau uiInfo-pszMessageText> dan uiInfo-pszCaption> harus ditentukan.

Bendera CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS dan CREDUI_FLAGS_GENERIC_CREDENTIALS saling eksklusif. Jika tidak ditentukan, kredensial adalah kredensial domain.

Jika CREDUI_FLAGS_GENERIC_CREDENTIALS tidak ditentukan atau CREDUI_FLAGS_COMPLETE_USERNAME ditentukan, nama yang ditik diperiksa sintaksisnya. Sintaks yang diperiksa berarti bahwa aturan yang sama digunakan seperti yang disiratkan oleh CredUIParseUserName. Jika nama yang ditik tidak valid, pengguna akan dimintai nama yang valid. Jika bagian domain dari nama yang ditik hilang, satu akan diberikan berdasarkan nama target.

Jika CREDUI_FLAGS_GENERIC_CREDENTIALS ditentukan dan CREDUI_FLAGS_VALIDATE_USERNAME juga ditentukan, nama yang ditik diperiksa sintaksnya. Jika nama yang ditik tidak valid, pengguna akan dimintai nama yang valid.

Jika CREDUI_FLAGS_GENERIC_CREDENTIALS ditentukan dan tidak CREDUI_FLAGS_COMPLETE_USERNAME maupun CREDUI_FLAGS_VALIDATE_USERNAME yang ditentukan, nama yang ditik tidak diperiksa sintaksnya dengan cara apa pun.

Jika tidak CREDUI_FLAGS_PERSIST atau CREDUI_FLAGS_DO_NOT_PERSIST diatur, pesan simpan ditampilkan, dan mengontrol apakah kredensial disimpan atau tidak.

Jika CREDUI_FLAGS_PROMPT_FOR_SAVE ditentukan, parameter pfSave tidak boleh NULL.

Bendera CREDUI_FLAGS_REQUIRE_SMARTCARD dan CREDUI_FLAGS_EXCLUDE_CERTIFICATES saling eksklusif. CredUICmdLinePromptForCredentials mendukung permintaan sertifikat kartu pintar atau kredensial berbasis kata sandi. Ini tidak mendukung sertifikat yang bukan sertifikat kartu pintar atau meminta keduanya pada satu panggilan.

Mode Panggilan

Penelepon akan mencoba mengakses sumber daya target, memanggil credui (meneruskan deskripsi sumber daya target dan status kegagalan), memanggil CredUIParseUserName, mengakses sumber daya target lagi, lalu memanggil CredUIConfirmCredentials.
Pemanggil dapat meminta kredensial tanpa mengakses sumber daya apa pun dengan melewati CREDUI_FLAGS_DO_NOT_PERSIST.

Informasi Target

Informasi Target adalah informasi tentang lokasi sumber daya yang akan diakses. Untuk daftar semua nama target potensial untuk sumber daya, panggil CredGetTargetInfo. CredGetTargetInfo mengembalikan informasi yang di-cache oleh paket autentikasi Negosiasi, NTLM, atau Kerberos ketika salah satu paket tersebut digunakan untuk mengautentikasi ke target bernama. CredGetTargetInfo mengembalikan beberapa atau semua nama berikut untuk target:

Nama server NetBIOS komputer
Nama server DNS komputer
Nama domain NetBIOS dari domain milik komputer
Nama domain DNS dari domain milik komputer
Nama pohon DNS dari pohon milik komputer
Nama paket yang mengumpulkan informasi

Bagian mana pun dari informasi ini bisa hilang jika informasi tidak berlaku untuk komputer target. Misalnya, komputer yang merupakan anggota grup kerja tidak memiliki nama domain NetBIOS. Komputer yang merupakan anggota domain Windows tidak memiliki nama domain DNS atau nama pohon DNS.

Kredensial disimpan di manajer kredensial berdasarkan nama target. Setiap nama target disimpan secara umum tanpa bertabrakan dengan kredensial yang sudah disimpan di manajer kredensial. Efek penting dari menyimpan kredensial berdasarkan nama target adalah bahwa pengguna tertentu hanya dapat memiliki satu kredensial per target yang disimpan di manajer kredensial.

Catatan

Header wincred.h mendefinisikan CredUICmdLinePromptForCredentials sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur 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 XP [hanya aplikasi desktop]
Server minimum yang didukung	Windows Server 2003 [hanya aplikasi desktop]
Target Platform	Windows
Header	wincred.h
Pustaka	Credui.lib
DLL	Credui.dll