Fonction CredUICmdLinePromptForCredentialsA (wincred.h)

Article
08/27/2023

La fonction CredUICmdLinePromptForCredentials invite et accepte les informations d’identification d’un utilisateur travaillant dans une application de ligne de commande (console). Le nom et le mot de passe tapés par l’utilisateur sont renvoyés à l’application appelante pour vérification.

Syntaxe

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

Paramètres

[in] pszTargetName

Pointeur vers une chaîne terminée par null qui contient le nom de la cible pour les informations d’identification, généralement un nom de serveur. Pour les connexions DFS, cette chaîne est de la forme ServerName\ShareName. Le paramètre pszTargetName est utilisé pour identifier les informations cibles et est utilisé pour stocker et récupérer les informations d’identification.

[in] pContext

Actuellement réservé et doit avoir la valeur NULL.

[in, optional] dwAuthError

Spécifie la raison pour laquelle l’invite d’informations d’identification est nécessaire. Un appelant peut passer ce paramètre d’erreur Windows, retourné par un autre appel d’authentification, pour permettre à la boîte de dialogue de prendre en charge certaines erreurs. Par exemple, si le mot de passe a expiré status code est passé, la boîte de dialogue invite l’utilisateur à modifier le mot de passe sur le compte.

[in, out] UserName

Pointeur vers une chaîne terminée par null qui contient le nom d’utilisateur des informations d’identification. Si une chaîne de longueur différente de zéro est spécifiée pour pszUserName, l’utilisateur est invité uniquement à entrer le mot de passe. Dans le cas d’informations d’identification autres que le nom d’utilisateur ou le mot de passe, un format marshalé des informations d’identification peut être transmis. Cette chaîne est créée en appelant CredMarshalCredential.

Cette fonction écrit le nom fourni par l’utilisateur dans cette mémoire tampon, en copiant un maximum de caractères ulUserNameMaxChars . La chaîne de ce format peut être convertie au format nom d’utilisateur/mot de passe en appelant la fonction CredUIParseUsername . La chaîne dans son format marshalé peut être transmise directement à un fournisseur de support de sécurité (SSP).

Si l’indicateur de CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’un formulaire qui ne doit pas être inspecté, imprimé ou conservé, sauf à le transmettre à CredUIParseUsername. Les résultats suivants de CredUIParseUsername ne peuvent être transmis qu’à une API d’authentification côté client telle que WNetAddConnection ou l’API SSP.

[in] ulUserBufferSize

Nombre maximal de caractères pouvant être copiés dans pszUserName , y compris le caractère null de fin.

Note CREDUI_MAX_USERNAME_LENGTH n’inclut pas le caractère null de fin.

[in, out] pszPassword

Pointeur vers une chaîne terminée par null qui contient le mot de passe des informations d’identification. Si une chaîne de longueur différente de zéro est spécifiée pour pszPassword, le paramètre password est prérempli avec la chaîne.

Cette fonction écrit le mot de passe fourni par l’utilisateur dans cette mémoire tampon, en copiant un maximum de caractères ulPasswordMaxChars . Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST n’est pas spécifié, la valeur retournée dans ce paramètre est d’un formulaire qui ne doit pas être inspecté, imprimé ou conservé, sauf à le transmettre à une fonction d’authentification côté client telle que WNetAddConnection ou une fonction SSP.

Lorsque vous avez terminé d’utiliser le mot de passe, effacez le mot de passe de la mémoire en appelant la fonction SecureZeroMemory . Pour plus d’informations sur la protection des mots de passe, consultez Gestion des mots de passe.

[in] ulPasswordBufferSize

Nombre maximal de caractères pouvant être copiés dans pszPassword , y compris le caractère null de fin.

Note CREDUI_MAX_PASSWORD_LENGTH n’inclut pas le caractère null de fin.

[in, out] pfSave

Pointeur vers un BOOL qui spécifie l’état initial du message Enregistrer et reçoit l’état du message Enregistrer une fois que l’utilisateur a répondu à l’invite de commandes. Si pfSave n’a pas la valeur NULL et que CredUIPromptForCredentials retourne NO_ERROR, pfSave retourne l’état du message Enregistrer . Si l’indicateur CREDUI_FLAGS_PERSIST est spécifié, le message Enregistrer ne s’affiche pas, mais est considéré comme « y ». Si l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST est spécifié et que CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX n’est pas spécifié, le message Enregistrer n’est pas affiché, mais est considéré comme « n ».

[in] dwFlags

Valeur DWORD qui spécifie un comportement spécial pour cette fonction. Cette valeur peut être une combinaison OR au niveau du bit de zéro ou plus des valeurs suivantes.

Valeur	Signification
CREDUI_FLAGS_ALWAYS_SHOW_UI	Affichez une interface utilisateur si les informations d’identification peuvent être retournées à partir d’informations d’identification existantes dans le gestionnaire d’informations d’identification. Cet indicateur n’est autorisé que si CREDUI_FLAGS_GENERIC_CREDENTIALS est également spécifié et n’est utilisé qu’avec CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_DO_NOT_PERSIST	N’affichez pas le message d’enregistrement ni les informations d’identification de stockage. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX peut également être passé pour afficher le message d’enregistrement uniquement et retourner le résultat dans pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Invite de nom d’utilisateur/mot de passe. Si le paramètre pszUserName est spécifié, le nom d’utilisateur est omis. Si les informations d’identification sont conservées, stockez le nom d’utilisateur transmis avec les informations d’identification.
CREDUI_FLAGS_EXPECT_CONFIRMATION	Spécifie que l’appelant appelle CredUIConfirmCredentials pour déterminer si les informations d’identification retournées sont réellement valides. Cela garantit que les informations d’identification non valides ne sont pas enregistrées dans le gestionnaire d’informations d’identification. Spécifiez cet indicateur, sauf si CREDUI_FLAGS_DO_NOT_PERSIST est spécifié.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Considérez les informations d’identification entrées par l’utilisateur comme des informations d’identification génériques.
CREDUI_FLAGS_INCORRECT_PASSWORD	Ignorez silencieusement cet indicateur.
CREDUI_FLAGS_PERSIST	N’affichez pas le message d’enregistrement, mais enregistrez les informations d’identification comme si l’utilisateur répondait « y ».
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Ignorez silencieusement cet indicateur.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Réservé à une utilisation ultérieure ; ne passez pas cet indicateur.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Utilisez un carte intelligent et demandez un code confidentiel. Si plusieurs carte intelligentes sont disponibles, sélectionnez l’une d’entre elles. Si le paramètre pszUserName transmet une chaîne qui n’est pas vide, la chaîne doit correspondre à l’UPN associé au certificat sur l’une des cartes à puce. Un UPN correspond si la chaîne correspond à l’ENSEMBLE de l’UPN sur le certificat ou si la chaîne correspond à la partie située à gauche du signe at (@) dans l’UPN du certificat. S’il existe une correspondance, le carte intelligent correspondant est sélectionné.
CREDUI_FLAGS_SERVER_CREDENTIAL	Cet indicateur n’est significatif que dans la localisation d’informations d’identification correspondantes pour préremplir la boîte de dialogue, en cas d’échec de l’authentification. Lorsque cet indicateur est spécifié, les informations d’identification génériques ne sont pas mises en correspondance. Elle n’a aucun effet lors de l’écriture d’informations d’identification. CredUI ne crée pas d’informations d’identification qui contiennent des caractères génériques. Tous les éléments trouvés ont été créés explicitement par l’utilisateur ou créés par programmation, comme cela se produit lorsqu’une connexion RAS est établie.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Affichez le message d’enregistrement et retournez TRUE dans le paramètre pfSave out si l’utilisateur répond « y », FALSE si l’utilisateur répond « n ». CREDUI_FLAGS_DO_NOT_PERSIST devez être spécifié pour utiliser cet indicateur.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Les informations d’identification sont des informations d’identification d’identification d’identification. Le paramètre pszTargetName spécifie le nom de la commande ou du programme en cours d’exécution. Il est utilisé à des fins d’invite uniquement.

Valeur retournée

La valeur de retour est un DWORD et peut être l’une des valeurs suivantes.

Valeur	Description
ERROR_INVALID_FLAGS	Cette status est retournée pour toutes les combinaisons d’indicateurs qui ne sont pas valides.
ERROR_INVALID_PARAMETER	PszTargetName a la valeur NULL, la chaîne vide ou est plus long que CREDUI_MAX_DOMAIN_LENGTH, ou pUiInfo n’a pas la valeur NULL et la structure CredUI_INFO pointée n’a pas satisfait à l’une des exigences suivantes : Le membre cbSize doit en être un. Si le membre hbmBanner n’est pas NULL, il doit être de type OBJ_BITMAP. Si le membre pszMessageText n’est pas NULL, il ne doit pas être supérieur à CREDUI_MAX_MESSAGE_LENGTH. Si le membre pszCaptionText n’est pas NULL, il ne doit pas être supérieur à CREDUI_MAX_CAPTION_LENGTH.
ERROR_NO_SUCH_LOGON_SESSION	Impossible d’utiliser le gestionnaire d’informations d’identification. En règle générale, cette erreur est gérée en appelant CredUICmdLinePromptForCredentials et en transmettant l’indicateur CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	L’utilisateur a choisi OK. Les variables pszUserName, pszPassword et pfSave retournent les valeurs documentées précédemment.

Remarques

Les indicateurs CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE et CREDUI_FLAGS_EXCLUDE_CERTIFICATE s’excluent mutuellement.

Si CREDUI_FLAGS_DO_NOT_PERSIST est spécifié, pszTargetName doit être spécifié ou uiInfo-pszMessageText> et uiInfo-pszCaption> doivent être spécifiés.

Les indicateurs CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS et CREDUI_FLAGS_GENERIC_CREDENTIALS s’excluent mutuellement. Si aucun n’est spécifié, les informations d’identification sont des informations d’identification de domaine.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS n’est pas spécifié ou si CREDUI_FLAGS_COMPLETE_USERNAME est spécifié, la syntaxe du nom typé est vérifiée. La syntaxe vérifiée signifie que les mêmes règles sont utilisées que celles qui sont implicites par CredUIParseUserName. Si le nom typé n’est pas valide, l’utilisateur est invité à en fournir un valide. Si la partie domaine du nom typé est manquante, elle est fournie en fonction du nom cible.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et CREDUI_FLAGS_VALIDATE_USERNAME est également spécifié, la syntaxe du nom typé est vérifiée. Si le nom typé n’est pas valide, l’utilisateur est invité à en fournir un valide.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME ne sont spécifiés, la syntaxe du nom typé n’est pas vérifiée.

Si ni CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST ne sont définis, le message d’enregistrement s’affiche et il contrôle si les informations d’identification sont enregistrées ou non.

Si CREDUI_FLAGS_PROMPT_FOR_SAVE est spécifié, le paramètre pfSave ne doit pas avoir la valeur NULL.

Les indicateurs CREDUI_FLAGS_REQUIRE_SMARTCARD et CREDUI_FLAGS_EXCLUDE_CERTIFICATES s’excluent mutuellement. CredUICmdLinePromptForCredentials prend en charge l’invite à fournir un certificat de carte intelligent ou des informations d’identification basées sur un mot de passe. Il ne prend pas en charge les certificats qui ne sont pas intelligents carte des certificats ou qui invitent les deux lors d’un seul appel.

Modes d’appel

L’appelant tente d’accéder à la ressource cible, appelle credui (en passant une description de la ressource cible et de l’échec status), appelle CredUIParseUserName, accède à nouveau à la ressource cible, puis appelle CredUIConfirmCredentials.
L’appelant peut demander des informations d’identification sans accéder aux ressources en passant CREDUI_FLAGS_DO_NOT_PERSIST.

Informations cibles

Les informations cibles sont des informations sur l’emplacement de la ressource à accéder. Pour obtenir la liste de tous les noms cibles potentiels d’une ressource, appelez CredGetTargetInfo. CredGetTargetInfo retourne les informations mises en cache par le package d’authentification Negotiate, NTLM ou Kerberos quand l’un de ces packages a été utilisé pour s’authentifier auprès de la cible nommée. CredGetTargetInfo retourne tout ou partie des noms suivants pour la cible :

Nom du serveur NetBIOS de l’ordinateur
Nom du serveur DNS de l’ordinateur
Nom de domaine NetBIOS du domaine auquel appartient l’ordinateur
Nom de domaine DNS du domaine auquel appartient l’ordinateur
Nom de l’arborescence DNS de l’arborescence à laquelle l’ordinateur appartient
Nom du package qui a collecté les informations

Toute partie de ces informations peut être manquante si les informations ne s’appliquent pas à l’ordinateur cible. Par instance, un ordinateur membre d’un groupe de travail n’a pas de nom de domaine NetBIOS. Un ordinateur membre d’un domaine Windows n’a pas de nom de domaine DNS ou de nom d’arborescence DNS.

Les informations d’identification sont stockées dans le gestionnaire d’informations d’identification en fonction du nom cible. Chaque nom cible est stocké de manière générale sans entrer en collision avec les informations d’identification déjà stockées dans le gestionnaire d’informations d’identification. Un effet important du stockage des informations d’identification par nom de cible est qu’un utilisateur particulier ne peut avoir qu’une seule information d’identification par cible stockée dans le gestionnaire d’informations d’identification.

Notes

L’en-tête wincred.h définit CredUICmdLinePromptForCredentials comme un alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. Le mélange de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	wincred.h
Bibliothèque	Credui.lib
DLL	Credui.dll