Función CredUIPromptForCredentialsA (wincred.h)
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 la biometría y las tarjetas inteligentes.
- CredUIPromptForWindowsCredentials es compatible con la especificación Common Criteria.
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 de 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 se reserva para uso futuro. Debe ser NULL.
[in, optional] dwAuthError
Especifica por qué se necesita el cuadro de diálogo de credenciales. Un llamador 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 y copia un máximo de caracteres ulUserNameMaxChars . Este formato se puede convertir al formato username/password mediante CredUIParseUsername. Un formato serializado se puede pasar directamente a un proveedor de soporte técnico de seguridad (SSP).
Si no se especifica la marca de CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no se debe inspeccionar, imprimir ni conservar distinto 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 parNombreDeUsuario\NombreDeDominio. En la salida, este parámetro recibe una cadena que contiene el par NombreDeUsuario nombreDeDominio\.
[in] ulUserNameBufferSize
Número máximo de caracteres que se pueden copiar en pszUserName , incluido 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 y copia un máximo de caracteres ulPasswordMaxChars . Si no se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST, el valor devuelto en este parámetro es de un formulario que no se debe inspeccionar, imprimir o conservar distinto 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, desactive la contraseña de la memoria llamando a la función SecureZeroMemory . Para obtener más información sobre cómo proteger las 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.
[in, out] save
Puntero a un 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 de la 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 la función devuelva 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 una combinación or bit a bit de cero o más de los valores siguientes.
| Valor | Significado |
|---|---|
|
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. |
|
Rellene el cuadro combinado con la solicitud de un nombre de usuario. |
|
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 . |
|
Rellene el cuadro combinado con solo nombre de usuario o contraseña. No muestre certificados ni tarjetas inteligentes en el cuadro combinado. |
|
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. |
|
Considere las credenciales especificadas por el usuario para que sean credenciales genéricas. |
|
Notifique al usuario las credenciales insuficientes mostrando la sugerencia de globo "Inicio de sesión incorrecto". |
|
No permita que el usuario cambie el nombre de usuario proporcionado. |
|
Rellene el cuadro combinado solo con la contraseña. No permita que se escriba un nombre de usuario. |
|
No muestre la casilla Guardar , pero la credencial se guarda como si se mostrara y seleccionara la casilla. |
|
Rellene el cuadro combinado solo con administradores locales. Windows XP Home Edition: Esta marca filtrará la cuenta de administrador conocida. |
|
Rellene el cuadro combinado solo con certificados y tarjetas inteligentes. No permita que se escriba un nombre de usuario. |
|
Rellene el cuadro combinado solo con certificados o tarjetas inteligentes. No permita que se escriba un nombre de usuario. |
|
Esta marca solo es significativa al buscar una credencial coincidente para rellenar previamente el cuadro de diálogo, si se produce un error de 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. |
|
Si la casilla está activada, muestre la casilla Guardar y devuelva TRUE en el parámetro de salida pfSave ; de lo contrario, devuelva FALSE. La casilla usa el valor de pfSave de forma predeterminada. |
|
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. |
|
Compruebe que el nombre de usuario es válido. |
Valor devuelto
El valor devuelto es DWORD y puede ser uno de los valores siguientes.
| Valor | Descripción |
|---|---|
|
El usuario eligió Cancelar. Los parámetros pszUserName y pszPassword no han cambiado. |
|
Este estado se devuelve para cualquiera de las configuraciones de marca que no son válidas. |
|
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:
|
|
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. |
|
El usuario eligió Aceptar. Los parámetros pszUserName, pszPassword y pfSave devolverán los valores documentados anteriormente. |
Comentarios
La función CredUIPromptForCredentials crea y muestra un cuadro de diálogo modal de aplicación. Una vez que se muestra el cuadro de diálogo y hasta que el usuario o la aplicación 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 se debe especificar uiInfo-pszMessageText> y uiInfo-pszCaption>.
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 clave (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 CREDUI_FLAGS_COMPLETE_USERNAME se especifica, se comprueba la sintaxis del nombre con tipo. 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 ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME, el nombre con tipo no se comprueba de ninguna manera.
Si no se establece 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), llamará a CredUIParseUserName, volverá a acceder al recurso de destino y, a continuación, llamará a CredUIConfirmCredentials.
- El autor de la llamada puede solicitar credenciales sin tener acceso a ningún recurso pasando CREDUI_FLAGS_DO_NOT_PERSIST.
- Para 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 del administrador de credenciales no es claramente válida para ese recurso.
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 posibles nombres de destino de un recurso, llame a CredGetTargetInfo. CredGetTargetInfo devuelve información almacenada en caché por el paquete de autenticación Negotiate, NTLM o Kerberos cuando se usó uno de esos paquetes 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
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 Convenciones para prototipos de función.
Requisitos
| Requisito | Value |
|---|---|
| Cliente mínimo compatible | Windows XP [solo aplicaciones de escritorio] |
| Servidor mínimo compatible | Windows Server 2003 [solo aplicaciones de escritorio] |
| Plataforma de destino | Windows |
| Encabezado | wincred.h |
| Library | Credui.lib |
| Archivo DLL | Credui.dll |