CredUIPromptForCredentialsA 函式 (wincred.h)
CredUIPromptForCredentials 函式會建立並顯示可設定的對話方塊,以接受來自使用者的認證資訊。
以 Windows Vista 或 Windows Server 2008 為目標的應用程式應該呼叫 CredUIPromptForWindowsCredentials ,而不是此函式,原因如下:
- CredUIPromptForWindowsCredentials 與目前的 Windows 使用者介面一致。
- CredUIPromptForWindowsCredentials 更容易延伸,允許整合其他驗證機制,例如生物特徵辨識和智慧卡。
- CredUIPromptForWindowsCredentials 符合 Common Criteria 規格。
語法
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
參數
[in, optional] pUiInfo
CREDUI_INFO結構的指標,其中包含自訂對話方塊外觀的資訊。
[in] pszTargetName
Null 終止字串的指標,其中包含認證的目標名稱,通常是伺服器名稱。 對於分散式檔案系統 (DFS) 連線,此字串的格式為ServerName\ShareName。 此參數可用來識別儲存和擷取認證時的目標資訊。
[in] pContext
這個參數保留給未來使用。 它必須是 Null。
[in, optional] dwAuthError
指定為何需要認證對話方塊。 呼叫端可以傳遞由另一個驗證呼叫傳回的這個 Windows 錯誤參數,以允許對話方塊容納特定錯誤。 例如,如果傳遞密碼過期狀態碼,對話方塊可能會提示使用者變更帳戶的密碼。
[in, out] pszUserName
包含認證使用者名稱之 Null 終止字串的指標。 如果傳遞非零長度字串,對話方塊的 UserName 選項會預先填入字串。 在UserName/Password以外的認證的情況下,可以傳入認證的封送處理格式。 此字串是由呼叫 CredMarshalCredential所建立。
此函式會將使用者提供的名稱複製到此緩衝區,複製最多 ulUserNameMaxChars 字元。 此格式可以使用CredUIParseUsername轉換成UserName/密碼格式。 封送處理的格式可以直接傳遞至 安全性支援提供者 , (SSP) 。
如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標,則此參數中傳回的值是不應該檢查、列印或保存的格式,而不是將它傳遞至 CredUIParseUsername。 CredUIParseUsername的後續結果只能傳遞至用戶端驗證函式,例如WNetAddConnection或 SSP 函式。
如果未將網域或伺服器指定為此參數的一部分,pszTargetName參數的值會當做網域來形成DomainName\UserName配對。 在輸出時,此參數會接收包含該 DomainName\UserName配對的字串。
[in] ulUserNameBufferSize
可以複製到 pszUserName 的最大字元數,包括終止的 Null 字元。
[in, out] pszPassword
包含認證密碼之 Null 終止字串的指標。 如果為 pszPassword指定非零長度字串,對話方塊的密碼選項將會預先填入字串。
此函式會將使用者提供的密碼複製到此緩衝區,複製最多 ulPasswordMaxChars 字元。 如果未指定CREDUI_FLAGS_DO_NOT_PERSIST旗標,則此參數中傳回的值是不應該檢查、列印或保存的表單,而不是將它傳遞至用戶端驗證函式,例如 WNetAddConnection 或 SSP 函式。
當您完成使用密碼時,請呼叫 SecureZeroMemory 函式 ,從記憶體清除密碼。 如需保護密碼的詳細資訊,請參閱 處理密碼。
[in] ulPasswordBufferSize
可以複製到 pszPassword 的最大字元數,包括終止的 Null 字元。
[in, out] save
BOOL的指標,指定 [儲存] 核取方塊的初始狀態,並在使用者回應對話方塊之後收到 [儲存] 核取方塊的狀態。 如果此值不是Null,而且CredUIPromptForCredentials會傳回NO_ERROR,則當使用者在對話方塊中選擇 [確定] 時,pfSave會傳回 [儲存] 核取方塊的狀態。
如果指定了CREDUI_FLAGS_PERSIST旗標,則不會顯示 [ 儲存 ] 核取方塊,但會被視為已選取。
如果指定CREDUI_FLAGS_DO_NOT_PERSIST旗標,且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX,則不會顯示 [ 儲存 ] 核取方塊,但會視為已清除。
需要使用 CredUI 提示使用者輸入認證,但不需要認證管理員所提供的認證管理服務的應用程式,可以使用 pfSave 在使用者關閉對話方塊之後接收 [ 儲存 ] 核取方塊的狀態。 若要這樣做,呼叫端必須在 dwFlags中指定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX。 設定CREDUI_FLAGS_DO_NOT_PERSIST和CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX時,應用程式會負責檢查函式傳回後的 *pfSave ,如果 *pfSave 為 TRUE,則應用程式必須採取適當的動作,在應用程式的資源內儲存使用者認證。
[in] dwFlags
指定此函式特殊行為的 DWORD 值。 這個值可以是零個或多個下列值的位OR 組合。
值 | 意義 |
---|---|
|
指定即使認證可以從認證管理員中的現有認證傳回,也會顯示使用者介面。 只有在同時指定CREDUI_FLAGS_GENERIC_CREDENTIALS時,才允許此旗標。 |
|
在下拉式方塊中填入使用者名稱的提示。 |
|
請勿儲存認證或顯示覆選框。 您可以使用此旗標傳遞CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX,只顯示 [ 儲存 ] 核取方塊,而且結果會在 pfSave 輸出參數中傳回。 |
|
僅以使用者名稱/密碼填入下拉式方塊。 不要在下拉式方塊中顯示憑證或智慧卡。 |
|
指定呼叫端會在檢查之後呼叫 CredUIConfirmCredentials ,以判斷傳回的認證是否實際有效。 此機制可確保不正確認證不會儲存至認證管理員。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST,否則在所有情況下都指定此旗標。 |
|
請考慮使用者輸入的認證為一般認證。 |
|
藉由顯示「登入失敗」批註提示,通知使用者認證不足。 |
|
不允許使用者變更提供的使用者名稱。 |
|
僅以密碼填入下拉式方塊。 不允許輸入使用者名稱。 |
|
請勿顯示 [ 儲存] 核取方塊,但認證會儲存為已顯示並選取方塊。 |
|
僅以本機系統管理員填入下拉式方塊。Windows XP Home Edition: 此旗標會篩選掉已知的系統管理員帳戶。 |
|
僅以憑證和智慧卡填入下拉式方塊。 不允許輸入使用者名稱。 |
|
僅以憑證或智慧卡填入下拉式方塊。 不允許輸入使用者名稱。 |
|
只有在尋找相符的認證以預先填入對話方塊時,此旗標才有意義,驗證應該會失敗。 指定此旗標時,萬用字元認證將不會相符。 撰寫認證時,它沒有任何作用。 CredUI 不會建立包含萬用字元的認證。 使用者明確建立或以程式設計方式建立任何找到的專案,就像建立 RAS 連線時一樣。 |
|
如果選取此核取方塊,請顯示 [儲存] 核取方塊,並在pfSave輸出參數中傳回TRUE,否則傳回FALSE。 核取方塊預設會使用 pfSave 中的值。 |
|
認證是「runas」 認證。 TargetName參數會指定要執行之命令或程式的名稱。 它僅用於提示用途。 |
|
檢查使用者名稱是否有效。 |
傳回值
傳回值是 DWORD ,可以是下列其中一個值。
值 | 描述 |
---|---|
|
使用者選擇 [取消]。 pszUserName和pszPassword參數尚未變更。 |
|
這個狀態會針對任何不正確旗標組態傳回。 |
|
pszTargetName為Null、空字串或大於 CREDUI_MAX_DOMAIN_LENGTH,或pUiInfo不是Null,而且指向的CredUI_INFO結構不符合下列其中一項需求:
|
|
無法使用認證管理員。 一般而言,呼叫 CredUIPromptForCredentials 並傳入 CREDUI_FLAGS_DO_NOT_PERSIST 旗標來處理此錯誤。 |
|
使用者選擇 [確定]。 pszUserName、pszPassword和pfSave參數會傳回稍早記載的值。 |
備註
CredUIPromptForCredentials 函式會建立並顯示應用程式強制回應對話方塊。 顯示對話方塊之後,直到使用者或應用程式關閉為止,應用程式中的其他視窗將無法變成作用中。
旗標CREDUI_FLAGS_REQUIRE_SMARTCARD、CREDUI_FLAGS_REQUIRE_CERTIFICATE和CREDUI_FLAGS_EXCLUDE_CERTIFICATE互斥。
如果指定了CREDUI_FLAGS_DO_NOT_PERSIST,就必須指定 pszTargetName ,或必須指定 uiInfo-pszMessageText > 和 uiInfo-pszCaption > 。
旗標CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS和CREDUI_FLAGS_GENERIC_CREDENTIALS互斥。 如果未指定認證,認證就是網域認證。
X509 憑證必須具有 增強的金鑰使用 方式, (EKU) 值 szOID_KP_SMARTCARD_LOGON ( 1.3.6.1.4.1.311.20.2.2) 。
Windowsxp: 此 EKU 值不需要顯示 X509 憑證。
如果未指定CREDUI_FLAGS_GENERIC_CREDENTIALS或指定CREDUI_FLAGS_COMPLETE_USERNAME,則會 檢查具類型的名稱。 語法檢查會套用 與 CredUIParseUserName所套用的相同規則。 如果具類型的名稱無效,系統會提示使用者輸入有效的名稱。 如果遺漏具型別名稱的網域部分,則會根據目標名稱提供一個網域部分。
如果指定了CREDUI_FLAGS_GENERIC_CREDENTIALS,而且也指定了CREDUI_FLAGS_VALIDATE_USERNAME,則會檢查具類型的名稱。 如果具類型的名稱無效,系統會提示使用者輸入有效的名稱。
如果指定CREDUI_FLAGS_GENERIC_CREDENTIALS,而且未指定CREDUI_FLAGS_COMPLETE_USERNAME或CREDUI_FLAGS_VALIDATE_USERNAME,則不會以任何方式檢查具型別的名稱。
如果未設定CREDUI_FLAGS_PERSIST或CREDUI_FLAGS_DO_NOT_PERSIST,則會顯示 [ 儲存 ] 核取方塊,並控制是否儲存認證。
呼叫模式
- 呼叫端會嘗試存取目標資源、呼叫 credui (傳遞目標資源的描述和失敗狀態) 、呼叫 CredUIParseUserName、再次存取目標資源,然後呼叫 CredUIConfirmCredentials。
- 呼叫端可以藉由傳遞CREDUI_FLAGS_DO_NOT_PERSIST來提示輸入認證,而不需要存取任何資源。
- 針對泛型認證,沒有驗證套件。 因此,應用程式必須存取認證才能執行驗證。 提示輸入認證,而不是在第一次驗證之前傳遞CREDUI_FLAGS_ALWAYS_SHOW_UI。 只有在認證管理員中沒有認證時,才會顯示使用者介面。 在應用程式內的所有後續訊息上,將會傳遞CREDUI_FLAGS_ALWAYS_SHOW_UI,因為認證管理員中的認證對於該資源而言顯然無效。
目標資訊是要存取之資源位置的相關資訊。 如需資源所有潛在目標名稱的清單,請呼叫 CredGetTargetInfo。 CredGetTargetInfo 會傳回當其中一個套件用來向具名目標進行驗證時,Negotiate、NTLM 或 Kerberos 驗證套件所快取的資訊。 CredGetTargetInfo 會傳回目標的一些或所有名稱:
- 電腦的 NetBIOS 伺服器名稱
- 電腦的 DNS 伺服器名稱
- 電腦所屬網域的 NetBIOS 功能變數名稱
- 電腦所屬網域的 DNS 功能變數名稱
- 電腦所屬樹狀結構的 DNS 樹狀結構名稱
- 收集資訊的封裝名稱
認證會根據目標名稱儲存在認證管理員中。 每個目標名稱通常會盡可能儲存,而不會與認證管理員中已儲存的認證發生衝突。 因為認證是以目標名稱儲存,所以特定使用者只能在認證管理員中儲存每個目標一個認證。
注意
wincred.h 標頭會根據 UNICODE 預處理器常數的定義,將 CredUIPromptForCredentials 定義為自動選取此函式的 ANSI 或 Unicode 版本。 混合使用編碼中性別名與非編碼中性的程式碼,可能會導致編譯或執行時間錯誤不符。 如需詳細資訊,請參閱 函式原型的慣例。
規格需求
最低支援的用戶端 | Windows XP [僅限傳統型應用程式] |
最低支援的伺服器 | Windows Server 2003 [僅限桌面應用程式] |
目標平臺 | Windows |
標頭 | wincred.h |
程式庫 | Credui.lib |
DLL | Credui.dll |