Función CredUICmdLinePromptForCredentialsW (wincred.h)

Artículo
03/08/2023

La función CredUICmdLinePromptForCredentials solicita y acepta información de credenciales de un usuario que trabaja en una aplicación de línea de comandos (consola). El nombre y la contraseña tipados por el usuario se devuelven a la aplicación que realiza la llamada para su comprobación.

Sintaxis

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsW(
  [in]           PCWSTR      pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PWSTR       UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PWSTR       pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

Parámetros

[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 DFS, esta cadena tiene el formato ServerName\ShareName. El parámetro pszTargetName se usa para identificar la información de destino y se usa para almacenar y recuperar la credencial.

[in] pContext

Actualmente reservado y debe ser NULL.

[in, optional] dwAuthError

Especifica por qué es necesario solicitar 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 pide al usuario que cambie la contraseña de la cuenta.

[in, out] UserName

Puntero a una cadena terminada en null que contiene el nombre de usuario de la credencial. Si se especifica una cadena de longitud distinta de cero para pszUserName, solo se le pedirá al usuario la contraseña. En el caso de las credenciales que no sean el nombre de usuario o la contraseña, se puede pasar un formato serializado de la credencial. Esta cadena se crea llamando a CredMarshalCredential.

Esta función escribe el nombre proporcionado por el usuario en este búfer y copia un máximo de caracteres ulUserNameMaxChars . La cadena en este formato se puede convertir al formato de nombre de usuario y contraseña llamando a la función CredUIParseUsername . La cadena en su 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 API de autenticación del lado cliente, como WNetAddConnection o la API de SSP.

[in] ulUserBufferSize

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, el parámetro password se rellenará previamente con la cadena.

Esta función escribe 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.

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

[in, out] pfSave

Puntero a un BOOL que especifica el estado inicial del mensaje Guardar y recibe el estado del mensaje Guardar después de que el usuario haya respondido al símbolo del sistema. Si pfSave no es NULL y CredUIPromptForCredentials devuelve NO_ERROR, pfSave devuelve el estado del mensaje Guardar . Si se especifica la marca CREDUI_FLAGS_PERSIST, no se muestra el mensaje Guardar , pero se considera "y". Si se especifica la marca CREDUI_FLAGS_DO_NOT_PERSIST y no se especifica CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX, no se muestra el mensaje Guardar , pero se considera "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.

Value	Significado
CREDUI_FLAGS_ALWAYS_SHOW_UI	Muestra una interfaz de usuario 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 y solo se usa junto con CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_DO_NOT_PERSIST	No muestre el mensaje de guardado ni almacene las credenciales. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX también se puede pasar para mostrar el mensaje de guardado solo y devolver el resultado en pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Solicite el nombre de usuario o la contraseña. Si se especifica el parámetro pszUserName , se omite el nombre de usuario. Si la credencial se conserva, almacene el nombre de usuario pasado con la credencial.
CREDUI_FLAGS_EXPECT_CONFIRMATION	Especifica que el autor de la llamada llamará a CredUIConfirmCredentials para determinar si las credenciales devueltas son realmente válidas. Esto garantiza que las credenciales que no sean válidas no se guarden en el administrador de credenciales. Especifique esta marca a menos que se especifique CREDUI_FLAGS_DO_NOT_PERSIST.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Considere las credenciales especificadas por el usuario una credencial genérica.
CREDUI_FLAGS_INCORRECT_PASSWORD	Omita silenciosamente esta marca.
CREDUI_FLAGS_PERSIST	No muestre el mensaje de guardado, pero guarde la credencial como si el usuario responda "y".
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Omita silenciosamente esta marca.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Reservado para uso futuro; no pase esta marca.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Use una tarjeta inteligente y solicite un PIN. Si hay más de una tarjeta inteligente disponible, seleccione una de ellas. Si el parámetro pszUserName pasa una cadena que no está vacía, la cadena debe coincidir con el UPN asociado al certificado en una de las tarjetas inteligentes. Un UPN coincide si la cadena coincide con el UPN completo del certificado o la cadena coincide con la parte a la izquierda del signo (@) en el UPN del certificado. Si hay una coincidencia, se selecciona la tarjeta inteligente coincidente.
CREDUI_FLAGS_SERVER_CREDENTIAL	Esta marca solo es significativa para 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. Cualquier encontrado fue creado explícitamente por el usuario o creado mediante programación, como sucede cuando se realiza una conexión RAS.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Muestra el mensaje de guardado y devuelve TRUE en el parámetro pfSave out si el usuario responde "y", FALSE si el usuario responde "n". CREDUI_FLAGS_DO_NOT_PERSIST se debe especificar para usar esta marca.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	La credencial es una credencial de ejecución. El parámetro pszTargetName especifica el nombre del comando o programa que se está ejecutando. Solo se usa para solicitar propósitos.

Valor devuelto

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

Value	Descripción
ERROR_INVALID_FLAGS	Este estado se devuelve para cualquiera de las combinaciones de marcas que no son válidas.
ERROR_INVALID_PARAMETER	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 apuntada 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 no es NULL, no debe ser mayor que CREDUI_MAX_MESSAGE_LENGTH. Si el miembro pszCaptionText 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 CredUICmdLinePromptForCredentials y pasando la marca CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	El usuario eligió Aceptar. Las variables pszUserName, pszPassword y pfSave devolverán los valores documentados anteriormente.

Comentarios

Las marcas de 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.

Si no se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS o CREDUI_FLAGS_COMPLETE_USERNAME se especifica, se comprueba la sintaxis del nombre con tipo. La sintaxis activada significa que CredUIParseUserName usa las mismas reglas que. 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 establecen CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST, se muestra el mensaje de guardado y controla si la credencial se guarda o no.

Si se especifica CREDUI_FLAGS_PROMPT_FOR_SAVE, el parámetro pfSave no debe ser NULL.

Las marcas CREDUI_FLAGS_REQUIRE_SMARTCARD y CREDUI_FLAGS_EXCLUDE_CERTIFICATES son mutuamente excluyentes. CredUICmdLinePromptForCredentials admite la solicitud de un certificado de tarjeta inteligente o una credencial basada en contraseña. No admite certificados que no sean certificados de tarjeta inteligente ni solicite ambos en una sola llamada.

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.

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

Cualquier parte de esta información puede faltar si la información no se aplica al equipo de destino. Por ejemplo, un equipo que sea miembro de un grupo de trabajo no tiene un nombre de dominio NetBIOS. Un equipo que sea miembro de un dominio de Windows no tiene un nombre de dominio DNS ni un nombre de árbol DNS.

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. Un efecto importante de almacenar credenciales por nombre de destino es que un usuario determinado solo puede tener una credencial por destino almacenada en el administrador de credenciales.

Nota

El encabezado wincred.h define CredUICmdLinePromptForCredentials 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


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