通过

CredUIPromptForCredentialsA 函数 （wincred.h）

  • 项目

CredUIPromptForCredentials 函数创建并显示一个可配置的对话框，该对话框接受来自用户的凭据信息。

面向 Windows Vista 或 Windows Server 2008 的应用程序应调用 CredUIPromptForWindowsCredentials 而不是此函数，原因如下：

语法

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/Password 格式。 封送格式可以直接传递到 安全支持提供程序（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，如果 *pfSaveTRUE，则应用程序必须采取适当的措施，以在应用程序的资源中保存用户凭据。

[in] dwFlags

DWORD 值，该值指定此函数的特殊行为。 此值可以是按位或 以下值中的零个或多个组合。

价值 意义
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
 指定即使可以从凭据管理器中的现有凭据返回凭据，也会显示用户界面。 仅当还指定了CREDUI_FLAGS_GENERIC_CREDENTIALS时，才允许此标志。
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
 使用提示填充用户名的组合框。
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
 不要存储凭据或显示复选框。 可以使用此标志传递CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX来仅显示 保存 复选框，结果在 pfSave 输出参数中返回。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
 仅使用用户名/密码填充组合框。 不要在组合框中显示证书或智能卡。
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
 指定调用方在检查后将调用 CredUIConfirmCredentials，以确定返回的凭据是否实际有效。 此机制可确保无效的凭据不会保存到凭据管理器。 在所有情况下指定此标志，除非指定CREDUI_FLAGS_DO_NOT_PERSIST。
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
 请考虑用户输入的凭据为通用凭据。
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
 通过显示“登录失败”气球提示通知用户凭据不足。
CREDUI_FLAGS_KEEP_USERNAME
0x100000
 不允许用户更改提供的用户名。
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
 仅使用密码填充组合框。 不允许输入用户名。
CREDUI_FLAGS_PERSIST
0x01000
 不要显示 “保存”复选框，但凭据将保存为显示和选中该框。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
 仅使用本地管理员填充组合框。Windows XP 家庭版：此标志将筛选出已知的管理员帐户。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
 仅使用证书和智能卡填充组合框。 不允许输入用户名。
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
 仅使用证书或智能卡填充组合框。 不允许输入用户名。
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
 如果身份验证失败，此标志仅在查找匹配凭据以预填充对话框时有意义。 指定此标志后，将不匹配通配符凭据。 写入凭据时，它不起作用。 CredUI 不会创建包含通配符的凭据。 任何发现都由用户显式创建或以编程方式创建，就像建立 RAS 连接时的情况一样。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
 如果选中该复选框，则显示 保存 复选框，并在 pfSave 输出参数中返回 true TRUE，否则返回 FALSE。 默认情况下，复选框使用 pfSave 中的值。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
 凭据是“runas”凭据。 TargetName 参数指定要运行的命令或程序的名称。 它仅用于提示目的。
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
 检查用户名是否有效。

返回值

返回值是 DWORD，可以是下列值之一。

价值 描述
ERROR_CANCELLED
 用户选择 取消。 pszUserName 和 pszPassword 参数未更改。
ERROR_INVALID_FLAGS
 对于无效的任何标志配置，将返回此状态。
ERROR_INVALID_PARAMETER
 pszTargetNameNULL、空字符串或长于 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。
ERROR_NO_SUCH_LOGON_SESSION
 无法使用凭据管理器。 通常，通过调用 CredUIPromptForCredentials 并传入 CREDUI_FLAGS_DO_NOT_PERSIST 标志来处理此错误。
NO_ERROR
 用户选择“确定”。 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 证书必须具有 szOID_KP_SMARTCARD_LOGON（1.3.6.1.4.1.311.20.2.2）的 增强型密钥使用（EKU）值。

Windows XP：此 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 域名。

凭据基于目标名称存储在凭据管理器中。 每个目标名称通常存储，而不会与凭据管理器中已存储的凭据相冲突。 由于凭据按目标名称存储，因此特定用户每个目标只能有一个凭据存储在凭据管理器中。

注意

wincred.h 标头将 CredUIPromptForCredentials 定义为基于 UNICODE 预处理器常量定义自动选择此函数的 ANSI 或 Unicode 版本的别名。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows XP [仅限桌面应用]
支持的最低服务器 Windows Server 2003 [仅限桌面应用]
目标平台 窗户
标头 wincred.h
库 Credui.lib
DLL Credui.dll

另请参阅

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection