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

Статья
08/27/2023

Функция 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

Указатель на строку с пустым завершением, которая содержит имя целевого объекта для учетных данных, обычно это имя сервера. Для подключений 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 или API SSP.

[in] ulUserBufferSize

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

Примечание CREDUI_MAX_USERNAME_LENGTH не содержит завершающий символ NULL .

[in, out] pszPassword

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

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

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

[in] ulPasswordBufferSize

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

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

[in, out] pfSave

Указатель на BOOL , который указывает начальное состояние сообщения Сохранить и получает состояние сообщения Сохранить после ответа пользователя на командную строку. Если 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 , указывающее специальное поведение для этой функции. Это значение может быть побитовой или комбинацией нуля или нескольких следующих значений.

Значение	Значение
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	Либо 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.
ERROR_NO_SUCH_LOGON_SESSION	Нельзя использовать диспетчер учетных данных. Как правило, эта ошибка обрабатывается путем вызова CredUICmdLinePromptForCredentials и передачи флага CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	Пользователь выбрал ОК. Переменные pszUserName, pszPassword и pfSave возвращают задокументированные ранее значения.

Если 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 или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	wincred.h
Библиотека	Credui.lib
DLL	Credui.dll