通过

CredUICmdLinePromptForCredentialsW 函数 (wincred.h)

  • 项目

CredUICmdLinePromptForCredentials 函数提示输入并接受在命令行 (控制台) 应用程序中工作的用户的凭据信息。 用户键入的名称和密码将传回调用方应用程序进行验证。

语法

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsW(
  [in]           PCWSTR      pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PWSTR       UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PWSTR       pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

参数

[in] pszTargetName

指向以 null 结尾的字符串的指针，该字符串包含凭据的目标名称，通常是服务器名称。 对于 DFS 连接，此字符串的格式为 ServerName\ShareName。 pszTargetName 参数用于标识目标信息，用于存储和检索凭据。

[in] pContext

当前保留，必须为 NULL。

[in, optional] dwAuthError

指定需要提示输入凭据的原因。 调用方可以传递由另一个身份验证调用返回的此 Windows 错误参数，以允许对话框容纳某些错误。 例如，如果传递了密码过期状态代码，对话框将提示用户更改帐户的密码。

[in, out] UserName

指向包含凭据用户名的 以 null 结尾的字符串的指针。 如果为 pszUserName 指定了非零长度字符串，则仅提示用户输入密码。 对于用户名/密码以外的凭据，可以传入凭据的封送格式。 此字符串是通过调用 CredMarshalCredential 创建的。

此函数将用户提供的名称写入此缓冲区，复制的最大 ulUserNameMaxChars 字符数。 此格式的字符串可以通过调用 CredUIParseUsername 函数转换为用户名/密码格式。 封送格式的字符串可以直接传递给 安全支持提供程序 (SSP) 。

如果未指定CREDUI_FLAGS_DO_NOT_PERSIST标志，则此参数中返回的值采用的形式，除了将其传递给 CredUIParseUsername 之外，不应对其进行检查、打印或持久保存。 CredUIParseUsername 的后续结果只能传递给客户端身份验证 API，例如 WNetAddConnection 或 SSP API。

[in] ulUserBufferSize

可复制到 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] pfSave

指向 BOOL 的指针，该指针指定 保存 消息的初始状态，并在用户响应命令提示符后接收 Save 消息的状态。 如果 pfSave 不为 NULL 且 CredUIPromptForCredentials 返回NO_ERROR， 则 pfSave 返回 保存 消息的状态。 如果指定了CREDUI_FLAGS_PERSIST标志，则不会显示 “保存” 消息，但被视为“y”。 如果指定了CREDUI_FLAGS_DO_NOT_PERSIST标志，并且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX，则不会显示 “保存” 消息，但被视为“n”。

[in] dwFlags

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

值 含义
CREDUI_FLAGS_ALWAYS_SHOW_UI
 如果可以从凭据管理器中的现有凭据返回凭据，则显示用户界面。 仅当还指定了CREDUI_FLAGS_GENERIC_CREDENTIALS并且仅与CREDUI_FLAGS_GENERIC_CREDENTIALS一起使用时，才允许使用此标志。
CREDUI_FLAGS_DO_NOT_PERSIST
 不显示保存消息或存储凭据。

还可以传递CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX以仅显示保存消息，并在 pfSave 中返回结果。
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
 提示输入用户名/密码。 如果指定 了 pszUserName 参数，则省略用户名。 如果保留凭据，请将传入的用户名与凭据一起存储。
CREDUI_FLAGS_EXPECT_CONFIRMATION
 指定调用方将调用 CredUIConfirmCredentials 以确定返回的凭据是否实际有效。 这可确保不会将无效的凭据保存到凭据管理器。 除非指定CREDUI_FLAGS_DO_NOT_PERSIST，否则请指定此标志。
CREDUI_FLAGS_GENERIC_CREDENTIALS
 将用户输入的凭据视为通用凭据。
CREDUI_FLAGS_INCORRECT_PASSWORD
 以无提示方式忽略此标志。
CREDUI_FLAGS_PERSIST
 不显示保存消息，但保存凭据，就像用户回答“y”。
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
 以无提示方式忽略此标志。
CREDUI_FLAGS_REQUIRE_CERTIFICATE
 保留供将来使用;不要传递此标志。
CREDUI_FLAGS_REQUIRE_SMARTCARD
 使用智能卡并提示输入 PIN。 如果有多个智能卡可用，请选择其中一个。 如果 pszUserName 参数传递的字符串不为空，则字符串必须与其中一个智能卡上的证书关联的 UPN 匹配。 如果字符串与证书上的整个 UPN 匹配，或者字符串与证书 UPN 中 at sign (@) 左侧的部分匹配，则 UPN 匹配。 如果存在匹配项，则选择匹配的智能卡。
CREDUI_FLAGS_SERVER_CREDENTIAL
 如果身份验证失败，此标志仅在查找匹配凭据以预填充对话框时才有意义。 指定此标志时，通配符凭据将不匹配。 写入凭据时，它不起作用。 CredUI 不会创建包含通配符的凭据。 找到的任何内容要么由用户显式创建，要么以编程方式创建，就像建立 RAS 连接时一样。
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
 如果用户回答“y”，则显示保存消息并在 pfSave out 参数中返回 TRUE;如果用户回答“n”，则返回 FALSE。 必须指定CREDUI_FLAGS_DO_NOT_PERSIST才能使用此标志。
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
 凭据是运行方式凭据。 pszTargetName 参数指定所运行的命令或程序的名称。 它仅用于提示目的。

返回值

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

值 说明
ERROR_INVALID_FLAGS
 对于任何无效的标志组合，将返回此状态。
ERROR_INVALID_PARAMETER
 pszTargetName 为 NULL、空字符串或长度超过 CREDUI_MAX_DOMAIN_LENGTH，或者 pUiInfo 不为 NULL 且指向的 CredUI_INFO 结构不符合以下要求之一：
  • cbSize 成员必须为 1。
  • 如果 hbmBanner 成员不为 NULL，则其类型必须为 OBJ_BITMAP。
  • 如果 pszMessageText 成员不为 NULL，则它不能大于 CREDUI_MAX_MESSAGE_LENGTH。
  • 如果 pszCaptionText 成员不为 NULL，则它不能大于 CREDUI_MAX_CAPTION_LENGTH。
ERROR_NO_SUCH_LOGON_SESSION
 不能使用凭据管理器。 通常，通过调用 CredUICmdLinePromptForCredentials 并传入 CREDUI_FLAGS_DO_NOT_PERSIST 标志来处理此错误。
NO_ERROR
 用户选择 “确定”。 pszUserName、pszPassword 和 pfSave 变量将返回前面记录的值。

注解

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标志互斥。 如果两者均未指定，则凭据为域凭据。

如果未指定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_FLAGS_PROMPT_FOR_SAVE， 则 pfSave 参数不得为 NULL。

CREDUI_FLAGS_REQUIRE_SMARTCARD和CREDUI_FLAGS_EXCLUDE_CERTIFICATES标志互斥。 CredUICmdLinePromptForCredentials 支持提示输入智能卡证书或基于密码的凭据。 它不支持不智能的证书卡证书，也不支持在单个调用中提示两者。

呼叫模式

  • 调用方将尝试访问目标资源，调用 credui (传递目标资源的说明和故障状态) ，调用 CredUIParseUserName，再次访问目标资源，然后调用 CredUIConfirmCredentials。
  • 调用方可以通过传递CREDUI_FLAGS_DO_NOT_PERSIST来提示输入凭据，而无需访问任何资源。
目标信息

目标信息是有关要访问的资源位置的信息。 有关资源的所有潜在目标名称的列表，请调用 CredGetTargetInfo。 使用其中一个包对命名目标进行身份验证时，CredGetTargetInfo 返回由 Negotiate、NTLM 或 Kerberos 身份验证包缓存的信息。 CredGetTargetInfo 为目标返回以下部分或全部名称：

  • 计算机的 NetBIOS 服务器名称
  • 计算机的 DNS 服务器名称
  • 计算机所属域的 NetBIOS 域名
  • 计算机所属域的 DNS 域名
  • 计算机所属树的 DNS 树名称
  • 收集信息的包的名称
如果信息不适用于目标计算机，则此信息中的任何部分都可能缺失。 例如，作为工作组成员的计算机没有 NetBIOS 域名。 作为 Windows 域成员的计算机没有 DNS 域名或 DNS 树名称。

凭据基于目标名称存储在凭据管理器中。 每个目标名称都尽可能存储，而不会与凭据管理器中已存储的凭据发生冲突。 按目标名称存储凭据的一个重要影响是，特定用户每个目标只能有一个凭据存储在凭据管理器中。

注意

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

要求

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

另请参阅

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUI_INFO

WNetAddConnection