Función CredUICmdLinePromptForCredentialsA (wincred.h)

Artículo
08/27/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 que escribe el usuario se devuelven a la aplicación que realiza la llamada para su comprobación.

Sintaxis

CREDUIAPI DWORD CredUICmdLinePromptForCredentialsA(
  [in]           PCSTR       pszTargetName,
  [in]           PCtxtHandle pContext,
  [in, optional] DWORD       dwAuthError,
  [in, out]      PSTR        UserName,
  [in]           ULONG       ulUserBufferSize,
  [in, out]      PSTR        pszPassword,
  [in]           ULONG       ulPasswordBufferSize,
  [in, out]      PBOOL       pfSave,
  [in]           DWORD       dwFlags
);

Parámetros

[in] pszTargetName

Puntero a un cadena terminadanull 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é se necesita solicitar 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 solicita al usuario que cambie la contraseña de la cuenta.

[in, out] UserName

Puntero a un cadena terminada en nullque contiene el nombre de usuario de 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, copiando un máximo de ulUserNameMaxChars caracteres. La cadena de este formato se puede convertir al formato de nombre de usuario o 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 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 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 de nulo de terminación .

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

[in, out] pszPassword

Puntero a un cadena terminada en nullque 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, 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 de nulo de terminación .

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

[in, out] pfSave

Puntero a un BOOL de 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 no 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 unOR bit a bit combinación de cero o más de los siguientes valores.

Valor	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 solo el mensaje de guardado 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 son 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 respondía a "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 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	Muestra el mensaje de guardado y devuelve TRUE en el parámetro pfSave pfSave out si el usuario responde "y", FALSE si el usuario responde "n". CREDUI_FLAGS_DO_NOT_PERSIST debe especificarse 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.

Valor	Descripción
ERROR_INVALID_FLAGS	Este estado se devuelve para cualquiera de las combinaciones de marcas 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 CredUICmdLinePromptForCredentials y pasando la marca CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	El usuario eligió Aceptar. Las pszUserName, pszPasswordy variables pfSave devolverán los valores documentados anteriormente.

Observaciones

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.

Si no se especifica CREDUI_FLAGS_GENERIC_CREDENTIALS o se especifica CREDUI_FLAGS_COMPLETE_USERNAME, el nombre con tipo se comprueba sintaxis. La sintaxis activada significa que las mismas reglas se usan como implícitas por 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 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), 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.

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. Un equipo que es 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 las 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 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