CredUICmdLinePromptForCredentialsA 函数 (wincred.h)

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

语法

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
);

参数

[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标志,则此参数中返回的值是不应检查、打印或保留的窗体,而不是将其传递给 CredUIParseUsernameCredUIParseUsername 的后续结果只能传递给客户端身份验证 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 的指针,指定 保存 消息的初始状态,并在用户响应命令提示符后接收 保存 消息的状态。 如果 pfSave为 NULLCredUIPromptForCredentials 返回NO_ERROR, pfSave 将返回 保存 消息的状态。 如果指定了CREDUI_FLAGS_PERSIST标志,则不会显示 “保存 ”消息,但被视为“y”。 如果指定了CREDUI_FLAGS_DO_NOT_PERSIST标志且未指定CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX,则不会显示 “保存 ”消息,但被视为“n”。

[in] dwFlags

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

Value 含义
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 匹配,或者字符串与证书 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 ,可以是以下值之一。

Value 描述
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
无法使用凭据管理器。 通常,通过调用 CredUICmdLinePromptForCredentials 并传入CREDUI_FLAGS_DO_NOT_PERSIST标志来处理此错误。
NO_ERROR
用户选择 “确定”。 pszUserNamepszPasswordpfSave 变量将返回前面记录的值。

注解

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来提示输入凭据,而无需访问任何资源。
目标信息

目标信息是有关要访问的资源的位置的信息。 有关资源的所有潜在目标名称的列表,请调用 CredGetTargetInfoCredGetTargetInfo 返回协商、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