Функция CredUICmdLinePromptForCredentialsW (wincred.h)

Статья
03/08/2023

Функция 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-terminated, содержащую имя целевого объекта для учетных данных, как правило, имя сервера. Для подключений DFS эта строка имеет форму ServerName\ShareName. Параметр pszTargetName используется для идентификации целевой информации и используется для хранения и получения учетных данных.

[in] pContext

В настоящее время зарезервированы и должны быть null.

[in, optional] dwAuthError

Указывает, почему требуется запрашивать учетные данные. Вызывающий объект может передать этот параметр ошибки Windows, возвращаемый другим вызовом проверки подлинности, чтобы разрешить диалоговое окно учесть определенные ошибки. Например, если код состояния с истекшим сроком действия пароля передается, диалоговое окно предложит пользователю изменить пароль в учетной записи.

[in, out] UserName

Указатель на строку null-terminated, содержащую имя пользователя учетных данных. Если строка ненулевой длины указана для pszUserName, пользователю будет предложено только для пароля. В случае учетных данных, отличных от имени пользователя или пароля, маршалированного формата учетных данных можно передать. Эта строка создается путем вызова CredMarshalCredential.

Эта функция записывает имя, предоставленное пользователем, в этот буфер, копируя максимум символов ulUserNameMaxChars. Строку в этом формате можно преобразовать в формат имени пользователя или пароля, вызвав функцию CredUIParseUsername. Строка в маршалируемом формате может передаваться непосредственно поставщику поддержки безопасности (SSP).

Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, имеет форму, которая не должна быть проверена, напечатана или сохранена, кроме передачи в CredUIParseUsername. Последующие результаты CredUIParseUsername могут передаваться только в клиентский API проверки подлинности, например WNetAddConnection или API SSP.

[in] ulUserBufferSize

Максимальное количество символов, которые можно скопировать в pszUserName включая завершающий символ null.

примечание CREDUI_MAX_USERNAME_LENGTH не включает завершающий символ null.

[in, out] pszPassword

Указатель на строку null-terminated, содержащую пароль для учетных данных. Если для pszPasswordуказана строка ненулевой длины, параметр пароля будет предварительно заполнен строкой.

Эта функция записывает пароль, предоставленный пользователем, в этот буфер, копируя максимум символов ulPasswordMaxChars. Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, имеет форму, которая не должна быть проверена, напечатана или сохранена, кроме передачи ее в функцию проверки подлинности на стороне клиента, например WNetAddConnection или функцию SSP.

По завершении использования пароля снимите пароль из памяти, вызвав функцию SecureZeroMemory. Дополнительные сведения о защите паролей см. в обработке паролей.

[in] ulPasswordBufferSize

Максимальное число символов, которые можно скопировать в pszPassword включая завершающийся символ null.

Примечание CREDUI_MAX_PASSWORD_LENGTH не включает завершающий символ null.

[in, out] pfSave

Указатель на boOL, указывающий начальное состояние сообщения "Сохранить" и получает состояние сообщения "Сохранить" после того, как пользователь ответил на командную строку. Если pfSave не NULL и CredUIPromptForCredentials возвращает NO_ERROR, pfSave возвращает состояние сообщения Save. Если указан флаг CREDUI_FLAGS_PERSIST, сообщение "Сохранить" не отображается, но считается "y". Если флаг CREDUI_FLAGS_DO_NOT_PERSIST указан и CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX не указан, сообщение "Сохранить" не отображается, но считается "n".

[in] dwFlags

Значение DWORD, указывающее специальное поведение для этой функции. Это значение может быть побитовойИЛИ сочетанием нуля или более следующих значений.

Ценность	Значение
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	Используйте смарт-карту и запрос ПИН-кода. Если доступно несколько смарт-карт, выберите один из них. Если параметр pszUserName передает строку, которая не пуста, строка должна соответствовать имени участника-пользователя, связанному с сертификатом на одной из смарт-карт. Имя участника-участника-участника совпадает, если строка соответствует всему имени участника-участника-участника или строка соответствует части слева от знака (@) в имени участника-участника-службы сертификата. Если имеется совпадение, выбрана соответствующая смарт-карта.
CREDUI_FLAGS_SERVER_CREDENTIAL	Этот флаг имеет смысл только при поиске соответствующих учетных данных для предварительного заполнения диалогового окна, если проверка подлинности завершается ошибкой. Если этот флаг указан, учетные данные подстановочного знака не будут совпадать. Он не действует при написании учетных данных. CredUI не создает учетные данные, содержащие подстановочные знаки. Любой найденный объект был создан явным образом пользователем или создан программным способом, как происходит при создании подключения RAS.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Отображение сообщения сохранения и возврата TRUE в параметре pfSave out, если пользователь отвечает на сообщение "y", FALSE, если пользователь отвечает на "n". CREDUI_FLAGS_DO_NOT_PERSIST необходимо указать для использования этого флага.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Учетные данные — это учетные данные запуска от имени. Параметр pszTargetName указывает имя выполняемой команды или программы. Он используется только для запроса.

Возвращаемое значение

Возвращаемое значение является DWORD и может быть одним из следующих значений.

Ценность	Описание
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	Пользователь выбрал OK. pszUserName, pszPassword, а переменные pfS ave 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 в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	wincred.h
библиотеки	Credui.lib
DLL	Credui.dll