Функция 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
Указатель на строку, завершающуюся значением NULL, которая содержит имя целевого объекта для учетных данных, как правило, имя сервера. Для подключений распределенной файловой системы (DFS) эта строка имеет форму имя_сервера\ShareName. Этот параметр используется для идентификации целевой информации при хранении и получении учетных данных.
[in] pContext
Этот параметр зарезервирован для дальнейшего использования. Он должен быть null.
[in, optional] dwAuthError
Указывает, почему требуется диалоговое окно учетных данных. Вызывающий объект может передать этот параметр ошибки Windows, возвращаемый другим вызовом проверки подлинности, чтобы разрешить диалоговое окно учесть определенные ошибки. Например, если код состояния с истекшим сроком действия пароля передается, диалоговое окно может предложить пользователю изменить пароль в учетной записи.
[in, out] pszUserName
Указатель на строку, завершающуюся значением NULL, содержащую имя пользователя для учетных данных. Если строка ненулевой длины передается, параметр UserName диалогового окна предварительно заполнен строкой. В случае учетных данных, отличных от userName/пароль, можно передать маршалированные формат учетных данных. Эта строка создается путем вызова CredMarshalCredential.
Эта функция копирует имя, предоставленное пользователем, в этот буфер, копируя максимум символов ulUserNameMaxChars. Этот формат можно преобразовать в формат UserName/password с помощью CredUIParseUsername. Маршалированные форматы можно передать непосредственно поставщику поддержки безопасности (SSP).
Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, имеет форму, которая не должна быть проверена, напечатана или сохранена, кроме передачи в CredUIParseUsername. Последующие результаты CredUIParseUsername могут передаваться только в функцию проверки подлинности на стороне клиента, например WNetAddConnection или функцию SSP.
Если домен или сервер не указан в рамках этого параметра, значение параметра pszTargetName используется в качестве домена для формирования пары domainName\UserName. В выходных данных этот параметр получает строку, содержащую пару DomainName\UserName.
[in] ulUserNameBufferSize
Максимальное количество символов, которые можно скопировать в pszUserName включая завершающийся символ NULL.
[in, out] pszPassword
Указатель на строку, завершающуюся значением NULL, которая содержит пароль для учетных данных. Если строка ненулевой длины указана для pszPassword, параметр пароля диалогового окна будет предварительно заполнен строкой.
Эта функция копирует предоставленный пользователем пароль в этот буфер, копируя максимум символов ulPasswordMaxChars. Если флаг CREDUI_FLAGS_DO_NOT_PERSIST не указан, значение, возвращаемое в этом параметре, имеет форму, которая не должна быть проверена, напечатана или сохранена, кроме передачи ее в функцию проверки подлинности на стороне клиента, например WNetAddConnection или функцию SSP.
По завершении использования пароля снимите пароль из памяти, вызвав функцию SecureZeroMemory. Дополнительные сведения о защите паролей см. в обработке паролей.
[in] ulPasswordBufferSize
Максимальное количество символов, которые можно скопировать в pszPassword, включая завершающий символ NULL.
[in, out] save
Указатель на
Если указан флаг 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 после возврата функции, а если *pfSaveTRUE, приложение должно выполнить соответствующее действие для сохранения учетных данных пользователя в ресурсах приложения.
[in] dwFlags
Значение DWORD, указывающее специальное поведение для этой функции. Это значение может быть побитовойИЛИ сочетанием нуля или более следующих значений.
| Ценность | Значение |
|---|---|
|
Указывает, что пользовательский интерфейс будет отображаться, даже если учетные данные можно вернуть из существующего учетных данных в диспетчере учетных данных. Этот флаг разрешен только в том случае, если CREDUI_FLAGS_GENERIC_CREDENTIALS также указан. |
|
Заполните поле со списком с запросом имени пользователя. |
|
Не сохраняйте учетные данные или флажки отображения. Вы можете передать CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX с этим флагом, чтобы отобразить только флажок "Сохранить", а результат возвращается в параметре вывода pfSave. |
|
Заполните поле со списком только именем пользователя или паролем. Не отображайте сертификаты или смарт-карты в поле со списком. |
|
Указывает, что вызывающий объект вызовет CredUIConfirmCredentials после проверки того, являются ли возвращенные учетные данные действительными. Этот механизм гарантирует, что недопустимые учетные данные не сохраняются в диспетчере учетных данных. Укажите этот флаг во всех случаях, если CREDUI_FLAGS_DO_NOT_PERSIST не указано. |
|
Рассмотрим учетные данные, введенные пользователем, как универсальные учетные данные. |
|
Уведомите пользователя о нехватке учетных данных, отображая подсказку "Вход в систему безуспешно". |
|
Не разрешайте пользователю изменять указанное имя пользователя. |
|
Заполните поле со списком только паролем. Не разрешайте вводить имя пользователя. |
|
Не отображайте флажок "Сохранить", но учетные данные сохраняются, как если бы поле отображалось и выбрано. |
|
Заполните поле со списком только локальными администраторами.Windows XP Home Edition: этот флаг отфильтрует известную учетную запись администратора. |
|
Заполните поле со списком только сертификатами и смарт-картами. Не разрешайте вводить имя пользователя. |
|
Заполните поле со списком только сертификатами или смарт-картами. Не разрешайте вводить имя пользователя. |
|
Этот флаг имеет смысл только при поиске соответствующих учетных данных для предварительного заполнения диалогового окна, если проверка подлинности завершается ошибкой. Если этот флаг указан, учетные данные подстановочного знака не будут совпадать. Он не действует при написании учетных данных. CredUI не создает учетные данные, содержащие подстановочные знаки. Любой найденный объект был создан явным образом пользователем или создан программным способом, как происходит при создании подключения RAS. |
|
Если установлен флажок, установите флажок "Сохранить" и верните TRUE в параметре вывода pfSave, в противном случае верните FALSE. По умолчанию флажок использует значение в pfSave. |
|
Учетные данные — это учетные данные runas. Параметр TargetName указывает имя выполняемой команды или программы. Он используется только для запроса. |
|
Убедитесь, что имя пользователя является допустимым. |
Возвращаемое значение
Возвращаемое значение является DWORD и может быть одним из следующих значений.
| Ценность | Описание |
|---|---|
|
Пользователь выбрал Отмена. Параметры pszUserName и pszPassword не изменились. |
|
Это состояние возвращается для любой из недопустимых конфигураций флагов. |
|
Либо pszTargetNamenull, пустая строка или длиннее CREDUI_MAX_DOMAIN_LENGTH, либо pUiInfo не NULL, а структура CredUI_INFO, указывающая на отсутствие одного из следующих требований:
|
|
Невозможно использовать диспетчер учетных данных. Как правило, эта ошибка обрабатывается путем вызова CredUIPromptForCredentials и передачи флага CREDUI_FLAGS_DO_NOT_PERSIST. |
|
Пользователь выбрал OK. Параметры |
Замечания
Функция 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-имя дерева, к которому принадлежит компьютер
- Имя пакета, который собрал сведения
Учетные данные хранятся в диспетчере учетных данных на основе целевого имени. Каждое целевое имя хранится как можно чаще без столкновения с учетными данными, уже хранящимися в диспетчере учетных данных. Так как учетные данные хранятся по целевому имени, конкретный пользователь может иметь только одну учетную запись на целевой объект, хранящийся в диспетчере учетных данных.
Заметка
Заголовок wincred.h определяет CredUIPromptForCredentials в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2003 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | wincred.h |
| библиотеки |
Credui.lib |
| DLL | Credui.dll |