CREDUIAPI DWORD CredUIPromptForCredentialsW(
[in, optional] PCREDUI_INFOW pUiInfo,
[in] PCWSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PWSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PWSTR 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 字符)的最大字符数。
注意 CREDUI_MAX_USERNAME_LENGTH不包括终止 null 字符。
[in, out] pszPassword
指向包含凭据密码的 null 终止字符串的指针。 如果为 pszPassword 指定了非零长度字符串,则对话框的密码选项将预先填充该字符串。
此函数将用户提供的密码复制到此缓冲区,复制最多 ulPasswordMaxChars 字符。 如果未指定CREDUI_FLAGS_DO_NOT_PERSIST标志,则此参数中返回的值是不应检查、打印或保留的表单,而不是将其传递给客户端身份验证函数(如 WNetAddConnection 或 SSP 函数)。
使用完密码后,通过调用 SecureZeroMemory 函数从内存中清除密码。 有关保护密码的详细信息,请参阅 处理密码。
[in] ulPasswordBufferSize
可复制到 pszPassword 的最大字符数,包括终止 null 字符。
注意 CREDUI_MAX_PASSWORD_LENGTH不包括终止 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 值,该值指定此函数的特殊行为。 此值可以是以下零个或多个值的按位或 组合。
Value
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
指定即使凭据可以从凭据管理器中的现有凭据返回凭据,也会显示用户界面。 仅当还指定了CREDUI_FLAGS_GENERIC_CREDENTIALS时,才允许此标志。
pszTargetName 为 NULL、空字符串或长于CREDUI_MAX_DOMAIN_LENGTH,或 pUiInfo 不是 NULL,并且指向的CredUI_INFO结构未满足以下要求之一:
- cbSize 成员必须是一个。
- 如果 hbmBanner 成员不是 NULL,则该成员的类型必须为 OBJ_BITMAP。
- 如果 pszMessageText 成员不是 NULL,则它不能大于 CREDUI_MAX_MESSAGE_LENGTH。
- 如果 pszCaptionText 成员不是 NULL,则它不能大于 CREDUI_MAX_CAPTION_LENGTH。
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.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 返回协商、NTLM 或 Kerberos 身份验证包缓存的信息,其中一个包用于向命名目标进行身份验证。 CredGetTargetInfo 返回目标的部分或全部名称:
- 计算机的 NetBIOS 服务器名称
- 计算机的 DNS 服务器名称
- 计算机所属域的 NetBIOS 域名
- 计算机所属域的 DNS 域名
- 计算机所属树的 DNS 树名称
- 收集信息的包的名称
如果信息不适用于目标计算机,则可能会缺少此信息的任何部分。 例如,属于工作组成员的计算机没有 NetBIOS 域名。
凭据基于目标名称存储在凭据管理器中。 每个目标名称通常存储,而不会与凭据管理器中已存储的凭据相冲突。 由于凭据按目标名称存储,因此特定用户只能为每个存储在凭据管理器中的一个凭据。