Función CredUIPromptForCredentialsA (wincred.h)

Artículo
08/27/2023

La función CredUIPromptForCredentials crea y muestra un cuadro de diálogo configurable que acepta información de credenciales de un usuario.

Las aplicaciones destinadas a Windows Vista o Windows Server 2008 deben llamar a CredUIPromptForWindowsCredentials en lugar de esta función, por los siguientes motivos:

CredUIPromptForWindowsCredentials es coherente con la interfaz de usuario actual de Windows.
CredUIPromptForWindowsCredentials es más extensible, lo que permite la integración de mecanismos de autenticación adicionales, como datos biométricos y tarjetas inteligentes.
CredUIPromptForWindowsCredentials es compatible con la especificación Criterios comunes.

Sintaxis

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

Parámetros

[in, optional] pUiInfo

Puntero a una estructura CREDUI_INFO que contiene información para personalizar la apariencia del cuadro de diálogo.

[in] pszTargetName

Puntero a una cadena terminada en null que contiene el nombre del destino para las credenciales, normalmente un nombre de servidor. Para las conexiones del Sistema de archivos distribuidos (DFS), esta cadena tiene el formato ServerName\ShareName. Este parámetro se usa para identificar la información de destino al almacenar y recuperar credenciales.

[in] pContext

Este parámetro está reservado para uso futuro. Debe ser NULL.

[in, optional] dwAuthError

Especifica por qué se necesita el cuadro de diálogo de credenciales. Un autor de llamada puede pasar este parámetro de error de Windows, devuelto por otra llamada de autenticación, para permitir que el cuadro de diálogo admita determinados errores. Por ejemplo, si se pasa el código de estado expirado de la contraseña, el cuadro de diálogo podría pedir al usuario que cambie la contraseña de la cuenta.

[in, out] pszUserName

Puntero a una cadena terminada en null que contiene el nombre de usuario de las credenciales. Si se pasa una cadena de longitud distinta de cero, la opción UserName del cuadro de diálogo se rellena previamente con la cadena. En el caso de las credenciales distintas de UserName/Password, se puede pasar un formato serializado de la credencial. Esta cadena se crea llamando a CredMarshalCredential.

Esta función copia el nombre proporcionado por el usuario en este búfer, copiando un máximo de ulUserNameMaxChars caracteres. Este formato se puede convertir en formato UserName/Password mediante CredUIParseUsername. Un formato serializado se puede pasar directamente a un proveedor de soporte técnico de seguridad de (SSP).

Si no se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no debe inspeccionarse, imprimirse ni conservarse aparte de pasarlo a CredUIParseUsername. Los resultados posteriores de credUIParseUsername solo se pueden pasar a una función de autenticación del lado cliente, como WNetAddConnection o una función SSP.

Si no se especifica ningún dominio o servidor como parte de este parámetro, el valor del parámetro pszTargetName se usa como dominio para formar un par DomainName\UserName. En la salida, este parámetro recibe una cadena que contiene que DomainName\par NombredeUsuario.

[in] ulUserNameBufferSize

Número máximo de caracteres que se pueden copiar en pszUserName incluido el carácter nulo de terminación.

Nota CREDUI_MAX_USERNAME_LENGTH no incluye el carácter nulo de terminación.

[in, out] pszPassword

Puntero a una cadena terminada en null que contiene la contraseña de las credenciales. Si se especifica una cadena de longitud distinta de cero para pszPassword, la opción de contraseña del cuadro de diálogo se rellenará previamente con la cadena.

Esta función copia la contraseña proporcionada por el usuario en este búfer, copiando un máximo de ulPasswordMaxChars caracteres. Si no se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no debe inspeccionarse, imprimirse o conservarse aparte de pasarlo a una función de autenticación del lado cliente, como WNetAddConnection o una función SSP.

Cuando haya terminado de usar la contraseña, borre la contraseña de la memoria llamando a la función SecureZeroMemory. Para obtener más información sobre cómo proteger contraseñas, consulte Control de contraseñas.

[in] ulPasswordBufferSize

Número máximo de caracteres que se pueden copiar en pszPassword incluido el carácter nulo de terminación.

Nota CREDUI_MAX_PASSWORD_LENGTH no incluye el carácter nulo de terminación.

[in, out] save

Puntero a una BOOL que especifica el estado inicial de la casilla Guardar y recibe el estado de la casilla Guardar después de que el usuario haya respondido al cuadro de diálogo. Si este valor no es NULL y CredUIPromptForCredentials devuelve NO_ERROR, pfSave devuelve el estado de la casilla Guardar cuando el usuario eligió Aceptar en el cuadro de diálogo.

Si se especifica la marca CREDUI_FLAGS_PERSIST, no se muestra la casilla guardar , pero se considera seleccionada.

Si se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST y no se especifica CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, no se muestra la casilla Guardar , pero se considera desactivada.

Una aplicación que necesita usar CredUI para solicitar al usuario las credenciales, pero no necesita los servicios de administración de credenciales proporcionados por el administrador de credenciales, puede usar pfSave para recibir el estado del casilla Guardar después de que el usuario cierre el cuadro de diálogo. Para ello, el autor de la llamada debe especificar CREDUI_FLAGS_DO_NOT_PERSIST y CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX en dwFlags. Cuando se establecen CREDUI_FLAGS_DO_NOT_PERSIST y CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, la aplicación es responsable de examinar *pfSave después de que se devuelva la función y, si *pfSave es TRUE, la aplicación debe realizar la acción adecuada para guardar las credenciales de usuario dentro de los recursos de la aplicación.

[in] dwFlags

Valor DWORD que especifica un comportamiento especial para esta función. Este valor puede ser unOR bit a bit combinación de cero o más de los siguientes valores.

Valor	Significado
CREDUI_FLAGS_ALWAYS_SHOW_UI 0x00080	Especifica que se mostrará una interfaz de usuario incluso si las credenciales se pueden devolver desde una credencial existente en el administrador de credenciales. Esta marca solo se permite si también se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_COMPLETE_USERNAME 0x00800	Rellene el cuadro combinado con el mensaje de un nombre de usuario.
CREDUI_FLAGS_DO_NOT_PERSIST 0x00002	No almacene las credenciales ni muestre las casillas. Puede pasar CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX con esta marca para mostrar solo la casilla guardar y el resultado se devuelve en el parámetro de salida pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES 0x00008	Rellene el cuadro combinado solo con nombre de usuario o contraseña. No muestre certificados ni tarjetas inteligentes en el cuadro combinado.
CREDUI_FLAGS_EXPECT_CONFIRMATION 0x20000	Especifica que el autor de la llamada llamará a CredUIConfirmCredentials después de comprobar si las credenciales devueltas son realmente válidas. Este mecanismo garantiza que las credenciales que no son válidas no se guarden en el administrador de credenciales. Especifique esta marca en todos los casos a menos que se especifique CREDUI_FLAGS_DO_NOT_PERSIST.
CREDUI_FLAGS_GENERIC_CREDENTIALS 0x40000	Considere las credenciales especificadas por el usuario para que sean credenciales genéricas.
CREDUI_FLAGS_INCORRECT_PASSWORD 0x00001	Notifique al usuario las credenciales insuficientes mostrando la sugerencia de globo "Inicio de sesión incorrecto".
CREDUI_FLAGS_KEEP_USERNAME 0x100000	No permita que el usuario cambie el nombre de usuario proporcionado.
CREDUI_FLAGS_PASSWORD_ONLY_OK 0x00200	Rellene el cuadro combinado solo con la contraseña. No permita que se escriba un nombre de usuario.
CREDUI_FLAGS_PERSIST 0x01000	No muestre la casilla Guardar, pero la credencial se guarda como si se mostrara y seleccionara la casilla.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR 0x00004	Rellene el cuadro combinado solo con administradores locales.Windows XP Home Edition: Esta marca filtrará la cuenta de administrador conocida.
CREDUI_FLAGS_REQUIRE_CERTIFICATE 0x00010	Rellene el cuadro combinado solo con certificados y tarjetas inteligentes. No permita que se escriba un nombre de usuario.
CREDUI_FLAGS_REQUIRE_SMARTCARD 0x00100	Rellene el cuadro combinado solo con certificados o tarjetas inteligentes. No permita que se escriba un nombre de usuario.
CREDUI_FLAGS_SERVER_CREDENTIAL 0x04000	Esta marca solo es significativa en la búsqueda de una credencial coincidente para rellenar previamente el cuadro de diálogo, si se produce un error en la autenticación. Cuando se especifica esta marca, no se coincidirán las credenciales con caracteres comodín. No tiene ningún efecto al escribir una credencial. CredUI no crea credenciales que contienen caracteres comodín. Los encontrados se crearon explícitamente por el usuario o se crearon mediante programación, como sucede cuando se realiza una conexión RAS.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX 0x00040	Si la casilla está activada, muestra la casilla guardar y devuelve true en el parámetro de salida pfSave pfSave; de lo contrario, devuelve FALSE. La casilla usa el valor de pfSave de forma predeterminada.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS 0x80000	La credencial es una credencial "runas". El parámetro TargetName especifica el nombre del comando o programa que se está ejecutando. Solo se usa para solicitar propósitos.
CREDUI_FLAGS_VALIDATE_USERNAME 0x00400	Compruebe que el nombre de usuario es válido.

Valor devuelto

El valor devuelto es un DWORD y puede ser uno de los siguientes valores.

Valor	Descripción
ERROR_CANCELLED	El usuario eligió Cancelar. Los parámetros pszUserName y pszPassword pszPassword no han cambiado.
ERROR_INVALID_FLAGS	Este estado se devuelve para cualquiera de las configuraciones de marca que no son válidas.
ERROR_INVALID_PARAMETER	El pszTargetName es NULL, la cadena vacía o más larga que CREDUI_MAX_DOMAIN_LENGTH, o pUiInfo no es NULL y la estructura de CredUI_INFO a la que se apunta no cumple uno de los siguientes requisitos: El miembro cbSize debe ser uno. Si el miembro hbmBanner no es NULL, debe ser de tipo OBJ_BITMAP. Si el miembro pszMessageText de no es NULL, no debe ser mayor que CREDUI_MAX_MESSAGE_LENGTH. Si el miembro pszCaptionText de no es NULL, no debe ser mayor que CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION	No se puede usar el administrador de credenciales. Normalmente, este error se controla llamando a CredUIPromptForCredentials y pasando la marca CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	El usuario eligió Aceptar. El pszUserName, pszPasswordy parámetros pfSave devolverá los valores documentados anteriormente.

Observaciones

La función CredUIPromptForCredentials crea y muestra un cuadro de diálogo modal de la aplicación. Una vez que se muestra el cuadro de diálogo y hasta que el usuario o la aplicación lo cierran, no se puede activar ninguna otra ventana de la aplicación.

Las marcas CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE y CREDUI_FLAGS_EXCLUDE_CERTIFICATE son mutuamente excluyentes.

Si se especifica CREDUI_FLAGS_DO_NOT_PERSIST, debe especificarse pszTargetName o uiInfo->pszMessageText y uiInfo->pszCaption debe especificarse.

Las marcas CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS y CREDUI_FLAGS_GENERIC_CREDENTIALS son mutuamente excluyentes. Si no se especifica ninguna, la credencial es una credencial de dominio.

Un certificado X509 debe tener un valor de uso mejorado de claves (EKU) de szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) que se mostrará.

Windows XP: Este valor de EKU no es necesario para mostrar certificados X509.

Si no se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS o se especifica CREDUI_FLAGS_COMPLETE_USERNAME, el nombre con tipo se comprueba sintaxis. La comprobación de sintaxis aplica las mismas reglas que aplica CredUIParseUserName. Si el nombre con tipo no es válido, se solicita al usuario uno válido. Si falta la parte de dominio del nombre con tipo, se proporcionará una en función del nombre de destino.

Si se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS y también se especifica CREDUI_FLAGS_VALIDATE_USERNAME, se comprueba la sintaxis del nombre con tipo. Si el nombre con tipo no es válido, se solicita al usuario uno válido.

Si se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS y no se especifica CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME, el nombre con tipo no se comprueba de ninguna manera.

Si no se establece ni CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST, se muestra la casilla Guardar y controla si se guarda la credencial.

Modos de llamada

El autor de la llamada intentará acceder al recurso de destino, llamará a credui (pasando una descripción del recurso de destino y el estado de error), llame a CredUIParseUserName, vuelva a acceder al recurso de destino y, a continuación, llame a CredUIConfirmCredentials.
El autor de la llamada puede solicitar credenciales sin tener acceso a ningún recurso pasando CREDUI_FLAGS_DO_NOT_PERSIST.
En el caso de las credenciales genéricas, no hay ningún paquete de autenticación. Por lo tanto, la aplicación debe tener acceso a la credencial para realizar la autenticación. Solicitar credenciales, no pasar CREDUI_FLAGS_ALWAYS_SHOW_UI antes de la primera autenticación. La interfaz de usuario solo aparecerá si no hay ninguna credencial en el administrador de credenciales. En todos los mensajes posteriores desde dentro de la aplicación, se pasará CREDUI_FLAGS_ALWAYS_SHOW_UI porque la credencial en el administrador de credenciales no es claramente válida para ese recurso.

Información de destino

La información de destino es información sobre la ubicación del recurso al que se va a acceder. Para obtener una lista de todos los nombres de destino potenciales de un recurso, llame a CredGetTargetInfo. credGetTargetInfo devuelve información almacenada en caché por el paquete de autenticación Negotiate, NTLM o Kerberos cuando uno de esos paquetes se usó para autenticarse en el destino con nombre. CredGetTargetInfo devuelve algunos o todos los nombres siguientes para el destino:

Nombre del servidor NetBIOS del equipo
Nombre del servidor DNS del equipo
Nombre de dominio netBIOS del dominio al que pertenece el equipo
Nombre de dominio DNS del dominio al que pertenece el equipo
Nombre del árbol DNS del árbol al que pertenece el equipo
Nombre del paquete que recopiló la información

Puede faltar cualquier parte de esta información si la información no se aplica al equipo de destino. Por ejemplo, un equipo que es miembro de un grupo de trabajo no tiene un nombre de dominio NetBIOS.

Las credenciales se almacenan en el administrador de credenciales en función del nombre de destino. Cada nombre de destino se almacena lo más generalmente posible sin colisionar con las credenciales ya almacenadas en el administrador de credenciales. Dado que las credenciales se almacenan por nombre de destino, un usuario determinado solo puede tener una credencial por destino almacenada en el administrador de credenciales.

Nota

El encabezado wincred.h define CredUIPromptForCredentials como alias que selecciona automáticamente la versión ANSI o Unicode de esta función en función de la definición de la constante de preprocesador UNICODE. La combinación del uso del alias neutral de codificación con código que no es neutral de codificación puede dar lugar a errores de coincidencia que dan lugar a errores de compilación o tiempo de ejecución. Para obtener más información, vea Conventions for Function Prototypes.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wincred.h
biblioteca de	Credui.lib
DLL de	Credui.dll