CredUICmdLinePromptForCredentialsA-Funktion (wincred.h)

Artikel
11/20/2024

Die CredUICmdLinePromptForCredentials Funktionsaufforderungen für Anmeldeinformationen von einem Benutzer, der in einer Befehlszeilenanwendung (Konsole) arbeitet, und akzeptiert diese. Der vom Benutzer eingegebene Name und das Kennwort werden zur Überprüfung an die aufrufende Anwendung zurückgesendet.

Syntax

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

Parameter

[in] pszTargetName

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

[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 aufnehmen kann. Wenn beispielsweise der Kennwortcode "Abgelaufen" übergeben wird, fordert das Dialogfeld den Benutzer auf, das Kennwort für das Konto zu ändern.

[in, out] UserName

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

Diese Funktion schreibt den vom Benutzer angegebenen Namen in diesen Puffer und kopiert maximal ulUserNameMaxChars Zeichen. Die Zeichenfolge in diesem Format kann in das Benutzernamen-/Kennwortformat konvertiert werden, indem sie die CredUIParseUsername-Funktion aufruft. Die Zeichenfolge im gemarstischen Format kann direkt an einen Sicherheitssupportanbieter (SSP) übergeben werden.

Wenn das CREDUI_FLAGS_DO_NOT_PERSIST Flag nicht angegeben ist, ist der in diesem Parameter zurückgegebene Wert ein Formular, das nicht überprüft, gedruckt oder beibehalten werden sollte, als es an CredUIParseUsernamezu ü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 endierenden NULL- Zeichens.

Hinweis enthält CREDUI_MAX_USERNAME_LENGTH nicht das beendende Nullzeichen Zeichen.

[in, out] pszPassword

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

Diese Funktion schreibt das vom Benutzer bereitgestellte 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 ein Formular, das nicht überprüft, gedruckt oder beibehalten werden sollte, außer es an eine clientseitige Authentifizierungsfunktion wie WNetAddConnection oder eine SSP-Funktion zu übergeben.

Wenn Sie mit der Verwendung des Kennworts fertig sind, löschen Sie das Kennwort aus dem Arbeitsspeicher, indem Sie die SecureZeroMemory-Funktion aufrufen. Weitere Informationen zum Schützen 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 endierenden Nullzeichens Zeichens.

Hinweis CREDUI_MAX_PASSWORD_LENGTH enthält nicht das beendende Nullzeichen Zeichen.

[in, out] pfSave

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

[in] dwFlags

Ein DWORD- Wert, der ein spezielles Verhalten für diese Funktion angibt. Dieser Wert kann ein bitweiserODER Kombination aus Null oder mehr der folgenden Werte sein.

Wert	Bedeutung
CREDUI_FLAGS_ALWAYS_SHOW_UI	Zeigt eine Benutzeroberfläche an, wenn die Anmeldeinformationen von einer vorhandenen Anmeldeinformation im Anmeldeinformations-Manager zurückgegeben werden können. Dieses Kennzeichen ist nur zulässig, wenn CREDUI_FLAGS_GENERIC_CREDENTIALS ebenfalls 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 anmeldeinformationen. CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX können auch übergeben werden, um die Speichernachricht nur anzuzeigen und das Ergebnis in pfSave-zurückzugeben.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES	Zur Eingabe des Benutzernamens/Kennworts auffordern. Wenn der pszUserName Parameter angegeben ist, 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, CREDUI_FLAGS_DO_NOT_PERSIST angegeben ist.
CREDUI_FLAGS_GENERIC_CREDENTIALS	Berücksichtigen Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen.
CREDUI_FLAGS_INCORRECT_PASSWORD	Ignorieren Sie diese Kennzeichnung im Hintergrund.
CREDUI_FLAGS_PERSIST	Zeigen Sie die Speichernachricht nicht an, speichern Sie die Anmeldeinformationen jedoch so, als ob der Benutzer "y" beantwortet habe.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR	Ignorieren Sie diese Kennzeichnung im Hintergrund.
CREDUI_FLAGS_REQUIRE_CERTIFICATE	Reserviert für die zukünftige Nutzung; dieses Flag nicht übergeben.
CREDUI_FLAGS_REQUIRE_SMARTCARD	Verwenden Sie eine Smartcard, und fordern Sie eine PIN an. Wenn mehrere Smartcards 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 des Zertifikats übereinstimmt, oder die Zeichenfolge mit dem Teil links neben dem At-Zeichen (@) im UPN des Zertifikats übereinstimmt. Wenn eine Übereinstimmung vorhanden ist, wird die entsprechende Smartcard ausgewählt.
CREDUI_FLAGS_SERVER_CREDENTIAL	Dieses Kennzeichen ist nur dann sinnvoll, wenn die Suche nach übereinstimmenden Anmeldeinformationen zum Vorfüllen des Dialogfelds sinnvoll ist, wenn die Authentifizierung fehlschlägt. Wenn dieses Kennzeichen angegeben ist, werden keine Wildcardanmeldeinformationen abgeglichen. Sie 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 beim Herstellen 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 Kennzeichen zu verwenden.
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS	Die Anmeldeinformationen sind als Anmeldeinformationen ausgeführt. Der pszTargetName Parameter gibt den Namen des auszuführenden Befehls oder Programms an. Sie 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	Dieser Status wird für eine der ungültigen Kennzeichenkombinationen zurückgegeben.
ERROR_INVALID_PARAMETER	Entweder pszTargetName- ist NULL-, die leere Zeichenfolge oder länger als CREDUI_MAX_DOMAIN_LENGTH oder pUiInfo- ist nicht NULL- und die CredUI_INFO Struktur, auf die verwiesen wurde, nicht eine der folgenden Anforderungen erfüllt: Das cbSize Mitglied muss eins sein. Wenn das hbmBanner Member 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. Normalerweise wird dieser Fehler behandelt, indem CredUICmdLinePromptForCredentials- aufgerufen und das CREDUI_FLAGS_DO_NOT_PERSIST-Flag übergeben wird.
NO_ERROR	Der Benutzer hat OKausgewählt. Die pszUserName-, pszPassword-und pfSave- Variablen geben die zuvor dokumentierten Werte zurück.

Bemerkungen

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- angegeben werden oder uiInfo->pszMessageText und uiInfo->pszCaption- angegeben werden.

Die kennzeichen 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 eine Domänenanmeldeinformation.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS nicht angegeben oder CREDUI_FLAGS_COMPLETE_USERNAME angegeben wird, wird der eingegebene Name Syntaxüberprüft. Syntax überprüft bedeutet, dass dieselben Regeln verwendet werden, wie von CredUIParseUserName. Wenn der eingegebene Name ungültig ist, wird der Benutzer aufgefordert, einen gültigen Namen einzugeben. Wenn der Domänenteil des eingegebenen Namens fehlt, wird ein Teil basierend auf dem Zielnamen angegeben.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und CREDUI_FLAGS_VALIDATE_USERNAME ebenfalls angegeben wird, wird der eingegebene Name syntaxgeprüft. Wenn der eingegebene Name ungültig ist, wird der Benutzer aufgefordert, einen gültigen Namen einzugeben.

Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und weder CREDUI_FLAGS_COMPLETE_USERNAME noch CREDUI_FLAGS_VALIDATE_USERNAME angegeben wird, wird der eingegebene Name nicht auf irgendeine Weise überprü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 parameter pfSave nicht NULL-sein.

Die Kennzeichen CREDUI_FLAGS_REQUIRE_SMARTCARD und CREDUI_FLAGS_EXCLUDE_CERTIFICATES schließen sich gegenseitig aus. CredUICmdLinePromptForCredentials- unterstützt das Anfordern eines Smartcardzertifikats oder einer kennwortbasierten Anmeldeinformationen. Es werden keine Zertifikate unterstützt, die keine Smartcardzertifikate sind oder bei einem einzelnen Anruf zur Eingabe beider Zertifikate aufgefordert werden.

Anrufmodi

Der Aufrufer versucht, auf die Zielressource zuzugreifen, credui aufzurufen (eine Beschreibung der Zielressource und den Fehlerstatus übergeben), CredUIParseUserNameaufrufen, erneut auf die Zielressource zugreifen und dann CredUIConfirmCredentialsaufrufen.
Der Aufrufer kann zur Eingabe von Anmeldeinformationen auffordern, ohne auf Ressourcen zuzugreifen, indem CREDUI_FLAGS_DO_NOT_PERSIST übergeben werden.

Zielinformation

Zielinformationen sind Informationen zum Speicherort der Ressource, auf die zugegriffen werden soll. Rufen Sie für eine Liste aller potenziellen Zielnamen für eine Ressource CredGetTargetInfoauf. CredGetTargetInfo 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

Alle Informationen können fehlen, wenn die Informationen nicht auf den Zielcomputer angewendet werden. Beispielsweise hat ein Computer, der Mitglied einer Arbeitsgruppe ist, keinen NetBIOS-Domänennamen. Ein Computer, der Mitglied einer Windows-Domäne ist, besitzt keinen DNS-Domänennamen oder DNS-Strukturnamen.

Anmeldeinformationen werden basierend auf dem Zielnamen im Anmeldeinformations-Manager gespeichert. Jeder Zielname wird so allgemein wie möglich gespeichert, ohne dass im Anmeldeinformations-Manager bereits gespeicherte Anmeldeinformationen kollidiert werden. Ein wichtiger Effekt beim Speichern von Anmeldeinformationen anhand des Zielnamens besteht darin, dass ein bestimmter Benutzer nur eine Anmeldeinformationen pro Ziel enthalten kann, die im Anmeldeinformations-Manager gespeichert sind.

Anmerkung

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

Anforderung	Wert
mindestens unterstützte Client-	Windows XP [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2003 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	wincred.h
Library	Credui.lib
DLL-	Credui.dll