CredUICmdLinePromptForCredentialsW-Funktion (wincred.h)

Artikel
08/27/2023

Die CredUICmdLinePromptForCredentials-Funktion fordert anmeldeinformationen von einem Benutzer an, der in einer Befehlszeilenanwendung (Konsolenanwendung) arbeitet, und akzeptiert diese. Der vom Benutzer eingegebene Name und das Kennwort werden zur Überprüfung an die aufrufende Anwendung zurückgegeben.

Syntax

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

Parameter

[in] pszTargetName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Namen des Ziels für die Anmeldeinformationen enthält, in der Regel einen Servernamen. Für DFS-Verbindungen hat diese Zeichenfolge das Format ServerName\ShareName. Der Parameter pszTargetName wird verwendet, um die Zielinformationen zu identifizieren, und wird zum Speichern und Abrufen der Anmeldeinformationen verwendet.

[in] pContext

Derzeit reserviert und muss NULL sein.

[in, optional] dwAuthError

Gibt an, warum die Aufforderung zur Eingabe von Anmeldeinformationen erforderlich ist. Ein Aufrufer kann diesen Windows-Fehlerparameter übergeben, der von einem anderen Authentifizierungsaufruf zurückgegeben wird, damit das Dialogfeld bestimmte Fehler berücksichtigen kann. Wenn das Kennwort beispielsweise abgelaufen ist, status Code übergeben wird, fordert das Dialogfeld den Benutzer auf, das Kennwort für das Konto zu ändern.

[in, out] UserName

Ein Zeiger auf eine NULL-Zeichenfolge, die den Benutzernamen der Anmeldeinformationen enthält. Wenn für pszUserName eine Zeichenfolge mit ungleicher Länge angegeben wird, wird der Benutzer nur zur Eingabe des Kennworts aufgefordert. Bei anderen Anmeldeinformationen als Benutzername/Kennwort kann ein gemarstes Format der Anmeldeinformationen übergeben werden. Diese Zeichenfolge wird durch Aufrufen von CredMarshalCredential erstellt.

Diese Funktion schreibt den vom Benutzer bereitgestellten Namen in diesen Puffer und kopiert maximal ulUserNameMaxChars-Zeichen . Die Zeichenfolge in diesem Format kann durch Aufrufen der CredUIParseUsername-Funktion in das Benutzernamen-/Kennwortformat konvertiert werden. Die Zeichenfolge im gemarshallten Format kann direkt an einen Sicherheitsunterstützungsanbieter (Security Support Provider , SSP) übergeben werden.

Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag nicht angegeben wird, ist der in diesem Parameter zurückgegebene Wert von einer Form, die nicht überprüft, gedruckt oder beibehalten werden sollte, außer an CredUIParseUsername zu übergeben. Die nachfolgenden Ergebnisse von CredUIParseUsername können nur an eine clientseitige Authentifizierungs-API wie WNetAddConnection oder die SSP-API übergeben werden.

[in] ulUserBufferSize

Die maximale Anzahl von Zeichen, die in pszUserName kopiert werden können, einschließlich des beendenden NULL-Zeichens .

Hinweis CREDUI_MAX_USERNAME_LENGTH enthält nicht das beendende NULL-Zeichen .

[in, out] pszPassword

Ein Zeiger auf eine NULL-Zeichenfolge, die das Kennwort für die Anmeldeinformationen enthält. Wenn für pszPassword eine Zeichenfolge mit ungleicher Länge angegeben wird, wird der Kennwortparameter mit der Zeichenfolge vorab ausgefüllt.

Diese Funktion schreibt das vom Benutzer angegebene Kennwort in diesen Puffer und kopiert maximal ulPasswordMaxChars-Zeichen . Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag nicht angegeben ist, ist der in diesem Parameter zurückgegebene Wert von einer Form, die nicht überprüft, gedruckt oder beibehalten werden darf, außer an eine clientseitige Authentifizierungsfunktion wie WNetAddConnection oder eine SSP-Funktion zu übergeben.

Wenn Sie das Kennwort verwendet haben, löschen Sie das Kennwort aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen. Weitere Informationen zum Schutz von Kennwörtern finden Sie unter Behandeln von Kennwörtern.

[in] ulPasswordBufferSize

Die maximale Anzahl von Zeichen, die in pszPassword kopiert werden können, einschließlich des beendenden NULL-Zeichens .

Hinweis CREDUI_MAX_PASSWORD_LENGTH enthält nicht das beendende NULL-Zeichen .

[in, out] pfSave

Ein Zeiger auf eine BOOL , der den Anfangszustand der Save-Nachricht angibt und den Status der Save-Nachricht empfängt, nachdem der Benutzer an die Eingabeaufforderung geantwortet hat. Wenn pfSave nicht NULL ist und CredUIPromptForCredentials NO_ERROR zurückgibt, gibt pfSave den Status der Save-Nachricht zurück. Wenn das CREDUI_FLAGS_PERSIST-Flag angegeben wird, wird die Save-Nachricht nicht angezeigt, sondern als "y" betrachtet. Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag angegeben und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX nicht angegeben ist, wird die Save-Nachricht nicht angezeigt, sondern als "n" betrachtet.

[in] dwFlags

Ein DWORD-Wert , der ein besonderes Verhalten für diese Funktion angibt. Dieser Wert kann eine bitweise-OR-Kombination aus 0 oder mehr der folgenden Werte sein.

Wert	Bedeutung
CREDUI_FLAGS_ALWAYS_SHOW_UI	Zeigen Sie eine Benutzeroberfläche an, wenn die Anmeldeinformationen von vorhandenen Anmeldeinformationen im Anmeldeinformations-Manager zurückgegeben werden können. Dieses Flag ist nur zulässig, wenn auch CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und nur in Verbindung mit CREDUI_FLAGS_GENERIC_CREDENTIALS verwendet wird.
CREDUI_FLAGS_DO_NOT_PERSIST	Zeigen Sie die Speichernachricht nicht an oder speichern Sie keine Anmeldeinformationen. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX kann auch übergeben werden, um nur die Speichernachricht anzuzeigen und das Ergebnis in pfSave zurückzugeben.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Fordern Sie den Benutzernamen/das Kennwort an. Wenn der parameter pszUserName angegeben wird, wird der Benutzername weggelassen. Wenn die Anmeldeinformationen beibehalten werden, speichern Sie den übergebenen Benutzernamen mit den Anmeldeinformationen.
CREDUI_FLAGS_EXPECT_CONFIRMATION	Gibt an, dass der Aufrufer CredUIConfirmCredentials aufruft , um zu bestimmen, ob die zurückgegebenen Anmeldeinformationen tatsächlich gültig sind. Dadurch wird sichergestellt, dass ungültige Anmeldeinformationen nicht im Anmeldeinformations-Manager gespeichert werden. Geben Sie dieses Flag an, es sei denn, es ist CREDUI_FLAGS_DO_NOT_PERSIST angegeben.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Betrachten Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen.
CREDUI_FLAGS_INCORRECT_PASSWORD	Ignorieren Sie dieses Flag im Hintergrund.
CREDUI_FLAGS_PERSIST	Zeigen Sie die Speichernachricht nicht an, sondern speichern Sie die Anmeldeinformationen so, als ob der Benutzer "y" antwortet.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Ignorieren Sie dieses Flag im Hintergrund.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Reserviert für zukünftige Verwendung; übergeben Sie dieses Flag nicht.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Verwenden Sie eine intelligente Karte und fordern Sie eine PIN an. Wenn mehrere intelligente Karte verfügbar sind, wählen Sie eine davon aus. Wenn der pszUserName-Parameter eine Zeichenfolge übergibt, die nicht leer ist, muss die Zeichenfolge mit dem UPN übereinstimmen, der dem Zertifikat auf einer der Smartcards zugeordnet ist. Ein UPN stimmt überein, wenn die Zeichenfolge mit dem gesamten UPN im Zertifikat übereinstimmt, oder wenn die Zeichenfolge mit dem Teil links neben dem At-Zeichen (@) im UPN des Zertifikats übereinstimmt. Wenn eine Übereinstimmung vorhanden ist, wird die übereinstimmende intelligente Karte ausgewählt.
CREDUI_FLAGS_SERVER_CREDENTIAL	Dieses Flag ist nur bei der Suche nach übereinstimmenden Anmeldeinformationen zum Vorabausfüllen des Dialogfelds von Bedeutung, falls die Authentifizierung fehlschlägt. Wenn dieses Flag angegeben wird, werden die Anmeldeinformationen für Die Wildcard nicht übereinstimmen. Es hat keine Auswirkung beim Schreiben von Anmeldeinformationen. CredUI erstellt keine Anmeldeinformationen, die Wildcardzeichen enthalten. Alle gefundenen Wurden entweder explizit vom Benutzer erstellt oder programmgesteuert erstellt, wie bei einer RAS-Verbindung.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX	Zeigen Sie die Speichernachricht an, und geben Sie true im Parameter pfSave out zurück, wenn der Benutzer "y" antwortet, FALSE , wenn der Benutzer "n" antwortet. CREDUI_FLAGS_DO_NOT_PERSIST muss angegeben werden, um dieses Flag verwenden zu können.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Bei den Anmeldeinformationen handelt es sich um ausführende Anmeldeinformationen. Der Parameter pszTargetName gibt den Namen des Befehls oder Programms an, der ausgeführt wird. Es wird nur zu Aufforderungszwecken verwendet.

Rückgabewert

Der Rückgabewert ist ein DWORD und kann einer der folgenden Werte sein.

Wert	BESCHREIBUNG
ERROR_INVALID_FLAGS	Diese status wird für jede der ungültigen Flagkombinationen zurückgegeben.
ERROR_INVALID_PARAMETER	Entweder ist pszTargetNameNULL, die leere Zeichenfolge oder länger als CREDUI_MAX_DOMAIN_LENGTH, oder pUiInfo ist nicht NULL , und die CredUI_INFO Struktur, auf die verwiesen wird, erfüllte keine der folgenden Anforderungen: Das cbSize-Element muss eins sein. Wenn das hbmBanner-Element nicht NULL ist, muss es vom Typ OBJ_BITMAP sein. Wenn das pszMessageText-Element nicht NULL ist, darf es nicht größer als CREDUI_MAX_MESSAGE_LENGTH sein. Wenn das pszCaptionText-Element nicht NULL ist, darf es nicht größer als CREDUI_MAX_CAPTION_LENGTH sein.
ERROR_NO_SUCH_LOGON_SESSION	Der Anmeldeinformations-Manager kann nicht verwendet werden. In der Regel wird dieser Fehler behandelt, indem CredUICmdLinePromptForCredentials aufgerufen und das flag CREDUI_FLAGS_DO_NOT_PERSIST übergeben wird.
NO_ERROR	Der Benutzer hat OK ausgewählt. Die Variablen pszUserName, pszPassword und pfSave geben die zuvor dokumentierten Werte zurück.

Hinweise

Die Flags CREDUI_FLAGS_REQUIRE_SMARTCARD, CREDUI_FLAGS_REQUIRE_CERTIFICATE und CREDUI_FLAGS_EXCLUDE_CERTIFICATE schließen sich gegenseitig aus.

Wenn CREDUI_FLAGS_DO_NOT_PERSIST angegeben ist, muss entweder pszTargetName oder uiInfo-pszMessageText> und uiInfo-pszCaption> angegeben werden.

Die flags CREDUI_FLAG_USERNAME_TARGET_CREDENTIALS und CREDUI_FLAGS_GENERIC_CREDENTIALS schließen sich gegenseitig aus. Wenn keines angegeben ist, handelt es sich bei den Anmeldeinformationen um Domänenanmeldeinformationen.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS nicht angegeben oder CREDUI_FLAGS_COMPLETE_USERNAME angegeben ist, wird der eingegebene Name syntaxgeprüft. Die überprüfte Syntax bedeutet, dass dieselben Regeln verwendet werden, wie sie von CredUIParseUserName impliziert werden. Wenn der eingegebene Name ungültig ist, wird der Benutzer zur Eingabe eines gültigen Namens aufgefordert. Wenn der Domänenteil des eingegebenen Namens fehlt, wird basierend auf dem Zielnamen einer angegeben.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und auch CREDUI_FLAGS_VALIDATE_USERNAME angegeben wird, wird der eingegebene Name syntaxgeprüft. Wenn der eingegebene Name ungültig ist, wird der Benutzer zur Eingabe eines gültigen Namens aufgefordert.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und weder CREDUI_FLAGS_COMPLETE_USERNAME noch CREDUI_FLAGS_VALIDATE_USERNAME angegeben wird, wird der typisierte Name in keiner Weise syntaxgeprüft.

Wenn weder CREDUI_FLAGS_PERSIST noch CREDUI_FLAGS_DO_NOT_PERSIST festgelegt sind, wird die Speichernachricht angezeigt und steuert, ob die Anmeldeinformationen gespeichert werden.

Wenn CREDUI_FLAGS_PROMPT_FOR_SAVE angegeben ist, darf der pfSave-Parameter nicht NULL sein.

Die flags CREDUI_FLAGS_REQUIRE_SMARTCARD und CREDUI_FLAGS_EXCLUDE_CERTIFICATES schließen sich gegenseitig aus. CredUICmdLinePromptForCredentials unterstützt die Aufforderung zur Eingabe eines Smart Karte-Zertifikats oder kennwortbasierter Anmeldeinformationen. Es werden keine Zertifikate unterstützt, die keine intelligenten Karte Zertifikate sind oder bei einem einzigen Aufruf zur Eingabe von beidem aufgefordert werden.

Anrufmodi

Der Aufrufer versucht, auf die Zielressource zuzugreifen, ruft credui auf (übergibt eine Beschreibung der Zielressource und den Fehler status), ruft CredUIParseUserName auf, greift erneut auf die Zielressource zu und ruft dann CredUIConfirmCredentials auf.
Der Aufrufer kann zur Eingabe von Anmeldeinformationen auffordern, ohne auf Ressourcen zuzugreifen, indem er CREDUI_FLAGS_DO_NOT_PERSIST.

Zielinformationen

Zielinformationen sind Informationen zum Speicherort der Ressource, auf die zugegriffen werden soll. Rufen Sie CredGetTargetInfo auf, um eine Liste aller potenziellen Zielnamen für eine Ressource anzuzeigen. CredGetTargetInfo gibt Informationen zurück, die vom Negotiate-, NTLM- oder Kerberos-Authentifizierungspaket zwischengespeichert wurden, wenn eines dieser Pakete zur Authentifizierung beim benannten Ziel verwendet wurde. CredGetTargetInfo gibt einige oder alle der folgenden Namen für das Ziel zurück:

NetBIOS-Servername des Computers
DNS-Servername des Computers
NetBIOS-Domänenname der Domäne, zu der der Computer gehört
DNS-Domänenname der Domäne, zu der der Computer gehört
DNS-Strukturname der Struktur, zu der der Computer gehört
Name des Pakets, das die Informationen gesammelt hat

Ein Teil dieser Informationen kann fehlen, wenn die Informationen nicht für den Zielcomputer gelten. Für instance verfügt ein Computer, der Mitglied einer Arbeitsgruppe ist, nicht über einen NetBIOS-Domänennamen. Ein Computer, der Mitglied einer Windows-Domäne ist, verfügt weder über einen DNS-Domänennamen noch über einen DNS-Strukturnamen.

Anmeldeinformationen werden im Anmeldeinformations-Manager basierend auf dem Zielnamen gespeichert. Jeder Zielname wird so allgemein wie möglich gespeichert, ohne mit anmeldeinformationen zu kollidieren, die bereits im Anmeldeinformations-Manager gespeichert sind. Ein wichtiger Effekt des Speicherns von Anmeldeinformationen nach Zielnamen besteht darin, dass ein bestimmter Benutzer nur über eine Anmeldeinformation pro Ziel verfügen kann, die im Anmeldeinformations-Manager gespeichert werden kann.

Hinweis

Der wincred.h-Header definiert CredUICmdLinePromptForCredentials als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht Codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.

Anforderungen


Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	wincred.h
Bibliothek	Credui.lib
DLL	Credui.dll