CredUICmdLinePromptForCredentialsA, fonction (wincred.h)

Article
11/20/2024

La fonction CredUICmdLinePromptForCredentials demande 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 repassé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 null-terminated 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 se présente sous 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 être NULL .

[in, optional] dwAuthError

Spécifie pourquoi l’invite d’informations d’identification est nécessaire. Un appelant peut transmettre 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 code d’état expiré du mot de passe a expiré, la boîte de dialogue invite l’utilisateur à modifier le mot de passe sur le compte.

[in, out] UserName

Pointeur vers une chaîne null-terminated qui contient le nom d’utilisateur d’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/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 ulUserNameMaxChars caractères. 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 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é autre que de le transmettre à CredUIParseUsername. Les résultats suivants de CredUIParseUsername peuvent être transmis uniquement à 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.

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

[in, out] pszPassword

Pointeur vers une chaîne null-terminated qui contient le mot de passe des informations d’identification. Si une chaîne différente de zéro est spécifiée pour pszPassword, le paramètre de mot de passe 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 ulPasswordMaxChars caractères. 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é autre que de 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 qui peuvent être copiés dans pszPassword y compris la fin caractère null.

Remarque 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’est pas NULL et CredUIPromptForCredentials retourne NO_ERROR, pfSave retourne l’état du message Enregistrer. Si l’indicateur CREDUI_FLAGS_PERSIST est spécifié, le message Enregistrer n’est pas affiché, 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 deOU de zéro ou plusieurs 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 utilisé uniquement conjointement avec CREDUI_FLAGS_GENERIC_CREDENTIALS.
CREDUI_FLAGS_DO_NOT_PERSIST	N’affichez pas le message d’enregistrement ou stockez les informations d’identification. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX peut également être passé pour afficher le message d’enregistrement uniquement et renvoyer le résultat dans pfSave.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Invitez le 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 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 a répondu « 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 une carte à puce et invitez un code confidentiel. Si plusieurs cartes à puce 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ée au certificat sur l’une des cartes à puce. Un UPN correspond si la chaîne correspond à l’UPN entier sur le certificat ou si la chaîne correspond à la partie à gauche du signe at (@) dans l’UPN du certificat. S’il existe une correspondance, la carte à puce correspondante est sélectionnée.
CREDUI_FLAGS_SERVER_CREDENTIAL	Cet indicateur est significatif uniquement dans la localisation d’informations d’identification correspondantes pour préremplir la boîte de dialogue, si l’authentification échoue. Lorsque cet indicateur est spécifié, les informations d’identification génériques ne sont pas mises en correspondance. Il 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. Les éléments trouvés ont été créés explicitement par l’utilisateur ou créés par programme, comme cela se produit lorsqu’une connexion RAS est établie.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Affichez le message d’enregistrement et renvoyez TRUE dans le paramètre pfSave de 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. Le paramètre pszTargetName spécifie le nom de la commande ou du programme en cours d’exécution. Il est utilisé uniquement à des fins d’invite.

Valeur de retour

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

Valeur	Description
ERROR_INVALID_FLAGS	Cet état est retourné pour l’une des combinaisons d’indicateurs qui ne sont pas valides.
ERROR_INVALID_PARAMETER	pszTargetName est NULL, la chaîne vide ou plus longue que CREDUI_MAX_DOMAIN_LENGTH, ou pUiInfo n’est pas NULL et la structure CredUI_INFO pointée n’a pas satisfait à l’une des exigences suivantes : Le membre cbSize doit ê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 passant l’indicateur de CREDUI_FLAGS_DO_NOT_PERSIST.
NO_ERROR	L’utilisateur a choisi OK. Les pszUserName, pszPasswordet variables 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 aucune des informations d’identification n’est spécifiée, les informations d’identification sont des informations d’identification de domaine.

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

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que CREDUI_FLAGS_VALIDATE_USERNAME est également spécifié, le nom typé est vérifié. Si le nom typé n’est pas valide, l’utilisateur est invité à en entrer un valide.

Si CREDUI_FLAGS_GENERIC_CREDENTIALS est spécifié et que ni CREDUI_FLAGS_COMPLETE_USERNAME ni CREDUI_FLAGS_VALIDATE_USERNAME n’est spécifié, le nom typé n’est pas vérifié de manière quelconque.

Si aucun CREDUI_FLAGS_PERSIST ni CREDUI_FLAGS_DO_NOT_PERSIST ne sont définis, le message d’enregistrement s’affiche et 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 être NULL .

Les indicateurs CREDUI_FLAGS_REQUIRE_SMARTCARD et CREDUI_FLAGS_EXCLUDE_CERTIFICATES s’excluent mutuellement. CredUICmdLinePromptForCredentials prend en charge l’invite d’un certificat de carte à puce ou d’informations d’identification basées sur un mot de passe. Il ne prend pas en charge les certificats qui ne sont pas des certificats de carte à puce ou qui invitent les deux sur 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 l’état d’échec), appelez CredUIParseUserName, accédez à nouveau à la ressource cible, puis appelez CredUIConfirmCredentials.
L’appelant peut demander des informations d’identification sans accéder à des 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 des informations mises en cache par le package d’authentification Negotiate, NTLM ou Kerberos lorsqu’un de ces packages a été utilisé pour s’authentifier auprès de la cible nommée. CredGetTargetInfo retourne certains noms ou tous les 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 appartient l’ordinateur
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 exemple, 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 ni 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é le plus généralement possible 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 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.

Note

L’en-tête wincred.h définit CredUICmdLinePromptForCredentials comme 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.

Exigences

Exigence	Valeur
client minimum pris en charge	Windows XP [applications de bureau uniquement]
serveur minimum pris en charge	Windows Server 2003 [applications de bureau uniquement]
plateforme cible	Windows
d’en-tête	wincred.h
bibliothèque	Credui.lib
DLL	Credui.dll