Поделиться через


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

Функция CredUIPromptForCredentials создает и отображает настраиваемое диалоговое окно, которое принимает учетные данные пользователя.

Приложения, предназначенные для Windows Vista или Windows Server 2008, должны вызывать CredUIPromptForWindowsCredentials вместо этой функции по следующим причинам:

  • CredUIPromptForWindowsCredentials соответствует текущему пользовательскому интерфейсу Windows.
  • CredUIPromptForWindowsCredentials является более расширяемым, что позволяет интегрировать дополнительные механизмы проверки подлинности, такие как биометрические данные и смарт-карты.
  • CredUIPromptForWindowsCredentials соответствует спецификации Common Criteria.

Синтаксис

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

Указатель на строку с пустым завершением, которая содержит имя целевого объекта для учетных данных, обычно это имя сервера. Для подключений распределенной файловой системы (DFS) эта строка имеет форму Имя_\сервера имя_сервера. Этот параметр используется для определения целевой информации при хранении и получении учетных данных.

[in] pContext

Этот параметр зарезервирован для использования в будущем. Он должен иметь значение NULL.

[in, optional] dwAuthError

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

[in, out] pszUserName

Указатель на строку, завершающуюся значением NULL, которая содержит имя пользователя для учетных данных. Если передается строка ненулевой длины, параметр UserName диалогового окна предварительно заполняется строкой. В случае учетных данных, отличных от userName/Password, можно передать маршалированные формат учетных данных. Эта строка создается путем вызова CredMarshalCredential.

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

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

Если в этом параметре не указан ни домен, ни сервер, значение параметра pszTargetName используется в качестве домена для формирования парыимя_пользователяdomainName\. В выходных данных этот параметр получает строку, содержащую эту паруимя_\пользователя_домена.

[in] ulUserNameBufferSize

Максимальное число символов, которые можно скопировать в 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] save

Указатель на bool, который указывает начальное состояние поля Сохранить проверка и получает состояние поля Сохранить проверка после ответа пользователя на диалоговое окно. Если это значение не равно NULL и CredUIPromptForCredentials возвращает NO_ERROR, то функция pfSave возвращает состояние поля Сохранить проверка, когда пользователь нажмет кнопку ОК в диалоговом окне.

Если указан флаг CREDUI_FLAGS_PERSIST, поле Сохранить проверка не отображается, но считается выбранным.

Если флаг CREDUI_FLAGS_DO_NOT_PERSIST указан, а CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX не указан, поле Сохранить проверка не отображается, но считается очищенным.

Приложение, которое должно использовать CredUI для запроса учетных данных пользователя, но не нуждается в службах управления учетными данными, предоставляемых диспетчером учетных данных, может использовать pfSave для получения состояния поля Сохранить проверка после закрытия пользователем диалогового окна. Для этого вызывающий объект должен указать CREDUI_FLAGS_DO_NOT_PERSIST и CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX в dwFlags. Если заданы CREDUI_FLAGS_DO_NOT_PERSIST и CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, приложение отвечает за проверку *pfSave после возврата функции. Если *pfSave имеет значение TRUE, приложение должно предпринять соответствующие действия для сохранения учетных данных пользователя в ресурсах приложения.

[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 Home Edition: Этот флаг отфильтрует общеизвестную учетную запись администратора.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
Заполните поле со списком только сертификатами и смарт-картами. Не разрешайте вводить имя пользователя.
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
Заполните поле со списком только сертификатами или смарт-картами. Не разрешайте вводить имя пользователя.
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
Этот флаг имеет смысл только при поиске соответствующих учетных данных для предварительного заполнения диалогового окна в случае сбоя проверки подлинности. Если этот флаг указан, учетные данные с подстановочными знаками не будут совпадать. Это не влияет на запись учетных данных. CredUI не создает учетные данные, содержащие подстановочные знаки. Все найденные были созданы явным образом пользователем или программным способом, как это происходит при подключении RAS.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
Если выбрано поле проверка, покажите поле Сохранить проверка и верните значение TRUE в выходном параметре pfSave, в противном случае — 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
Либо 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
Нельзя использовать диспетчер учетных данных. Как правило, эта ошибка обрабатывается путем вызова 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 должен иметь расширенное значение использования ключа (EKU) szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) для отображения.

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 возвращает сведения, кэшированные пакетом проверки подлинности Negotiate, NTLM или Kerberos, когда один из этих пакетов использовался для проверки подлинности в именованный целевой объект. CredGetTargetInfo возвращает некоторые или все следующие имена для целевого объекта:

  • NetBIOS-имя сервера компьютера
  • Имя DNS-сервера компьютера
  • NetBIOS-имя домена, к которому принадлежит компьютер
  • DNS-имя домена, к которому принадлежит компьютер
  • DNS-имя дерева, к которому принадлежит компьютер
  • Имя пакета, который собрал сведения
Любая часть этих сведений может отсутствовать, если эти сведения не относятся к целевому компьютеру. Например, компьютер, который входит в рабочую группу, не имеет доменного имени NetBIOS.

Учетные данные хранятся в диспетчере учетных данных на основе целевого имени. Каждое имя целевого объекта хранится как можно чаще, не сталкиваясь с учетными данными, которые уже хранятся в диспетчере учетных данных. Так как учетные данные хранятся по имени целевого объекта, конкретный пользователь может иметь только одну учетную запись для каждого целевого объекта, хранящегося в диспетчере учетных данных.

Примечание

Заголовок wincred.h определяет CredUIPromptForCredentials в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

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

См. также раздел

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection