CredUICmdLinePromptForCredentialsA-Funktion (wincred.h)
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 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-endende Zeichenfolge, die den Namen des Ziels für die Anmeldeinformationen enthält, in der Regel einen Servernamen. Für DFS-Verbindungen hat diese Zeichenfolge die Form ServerName\ShareName. Der Parameter pszTargetName wird verwendet, um die Zielinformationen zu identifizieren und die Anmeldeinformationen zu speichern und abzurufen.
[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-endende Zeichenfolge, die den Benutzernamen der Anmeldeinformationen enthält. Wenn eine Zeichenfolge ungleich null für pszUserName angegeben wird, wird der Benutzer nur zur Eingabe des Kennworts aufgefordert. Bei anderen Anmeldeinformationen als Benutzername/Kennwort kann ein gemarshalltes Format der Anmeldeinformationen übergeben werden. Diese Zeichenfolge wird durch Aufrufen von CredMarshalCredential erstellt.
Diese Funktion schreibt den vom Benutzer bereitgestellten Namen in diesen Puffer, wobei maximal ulUserNameMaxChars-Zeichen kopiert werden. 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 flag CREDUI_FLAGS_DO_NOT_PERSIST nicht angegeben wird, hat der in diesem Parameter zurückgegebene Wert eine Form, die nicht überprüft, gedruckt oder beibehalten werden soll, außer der Übergabe an CredUIParseUsername. 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 abschließenden NULL-Zeichens .
[in, out] pszPassword
Ein Zeiger auf eine NULL-endende Zeichenfolge, die das Kennwort für die Anmeldeinformationen enthält. Wenn für pszPassword eine Zeichenfolge ungleich null angegeben wird, wird der Parameter password mit der Zeichenfolge vorab ausgefüllt.
Diese Funktion schreibt das vom Benutzer bereitgestellte Kennwort in diesen Puffer, wobei maximal ulPasswordMaxChars-Zeichen kopiert werden. Wenn das flag CREDUI_FLAGS_DO_NOT_PERSIST nicht angegeben wird, hat der in diesem Parameter zurückgegebene Wert eine Form, die nicht überprüft, gedruckt oder beibehalten werden sollte, außer an eine clientseitige Authentifizierungsfunktion wie WNetAddConnection oder eine SSP-Funktion zu übergeben.
Wenn Sie die Verwendung des Kennworts abgeschlossen haben, 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 abschließenden NULL-Zeichens .
[in, out] pfSave
Ein Zeiger auf eine BOOL , die 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 flag CREDUI_FLAGS_PERSIST angegeben ist, wird die Nachricht Speichern nicht angezeigt, sondern als "y" betrachtet. Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag angegeben ist und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX nicht angegeben ist, wird die Save-Nachricht nicht angezeigt, sondern als "n".
[in] dwFlags
Ein DWORD-Wert , der ein spezielles Verhalten für diese Funktion angibt. Dieser Wert kann eine bitweise OR-Kombination aus null oder mehr der folgenden Werte sein.
| Wert | Bedeutung |
|---|---|
|
Zeigen Sie eine Benutzeroberfläche an, wenn die Anmeldeinformationen von einer vorhandenen Anmeldeinformation 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. |
|
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. |
|
Aufforderung zur Eingabe des Benutzernamens/Kennworts. Wenn der Parameter pszUserName angegeben ist, wird der Benutzername weggelassen. Wenn die Anmeldeinformationen beibehalten werden, speichern Sie den übergebenen Benutzernamen mit den Anmeldeinformationen. |
|
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. |
|
Betrachten Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen. |
|
Ignorieren Sie dieses Flag im Hintergrund. |
|
Zeigen Sie die Speichernachricht nicht an, sondern speichern Sie die Anmeldeinformationen so, als ob der Benutzer "y" antwortet. |
|
Ignorieren Sie dieses Flag im Hintergrund. |
|
Für zukünftige Verwendung reserviert; übergeben Sie dieses Flag nicht. |
|
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 auf dem 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 entsprechende intelligente Karte ausgewählt. |
|
Dieses Flag ist nur für die Suche nach übereinstimmenden Anmeldeinformationen sinnvoll, um das Dialogfeld vorab auszufüllen, falls die Authentifizierung fehlschlägt. Wenn dieses Flag angegeben ist, werden die Wildcard-Anmeldeinformationen nicht abgeglichen. 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 es bei einer RAS-Verbindung der Fall ist. |
|
Zeigen Sie die Save-Nachricht an, und geben Sie true im pfSave out-Parameter 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. |
|
Die Anmeldeinformationen sind ausführende Anmeldeinformationen. Der Parameter pszTargetName gibt den Namen des Befehls oder Programms an, das ausgeführt wird. Es wird nur zu Eingabeaufforderungszwecken verwendet. |
Rückgabewert
Der Rückgabewert ist ein DWORD und kann einer der folgenden Werte sein.
| Wert | BESCHREIBUNG |
|---|---|
|
Diese status wird für alle ungültigen Flagkombinationen zurückgegeben. |
|
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:
|
|
Der Anmeldeinformations-Manager kann nicht verwendet werden. In der Regel wird dieser Fehler durch Aufrufen von CredUICmdLinePromptForCredentials und Übergeben des CREDUI_FLAGS_DO_NOT_PERSIST-Flags behandelt. |
|
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, ist der typisierte Name syntaxgeprüft. Die überprüfte Syntax bedeutet, dass dieselben Regeln verwendet werden, die von CredUIParseUserName impliziert werden. Wenn der eingegebene Name ungültig ist, wird der Benutzer zur Eingabe eines gültigen Namen aufgefordert. Wenn der Domänenteil des eingegebenen Namens fehlt, wird einer basierend auf dem Zielnamen angegeben.
Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben und auch CREDUI_FLAGS_VALIDATE_USERNAME angegeben wird, wird der typisierte Name syntaxgeprüft. Wenn der eingegebene Name ungültig ist, wird der Benutzer zur Eingabe eines gültigen Namen aufgefordert.
Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist und weder CREDUI_FLAGS_COMPLETE_USERNAME noch CREDUI_FLAGS_VALIDATE_USERNAME angegeben ist, 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 sie steuert, ob die Anmeldeinformationen gespeichert werden oder nicht.
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 nach einem Smart Karte-Zertifikat oder kennwortbasierten Anmeldeinformationen. Es werden keine Zertifikate unterstützt, die keine smarten Karte Zertifikate sind oder bei einem einzelnen Aufruf zu beiden Aufrufen aufgefordert werden.
Aufrufmodi
- Der Aufrufer versucht, auf die Zielressource zuzugreifen, ruft credui auf (übergeben eine Beschreibung der Zielressource und des Fehlers 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 übergeben.
Zielinformationen sind Informationen über den Speicherort der Ressource, auf die zugegriffen werden soll. Rufen Sie CredGetTargetInfo auf, um eine Liste aller potenziellen Zielnamen für eine Ressource zu erhalten. CredGetTargetInfo gibt Informationen zurück, die vom Negotiate-, NTLM- oder Kerberos-Authentifizierungspaket zwischengespeichert wurden, als 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
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 Zielname ist, dass ein bestimmter Benutzer nur eine Anmeldeinformation pro Ziel im Anmeldeinformations-Manager speichern kann.
Hinweis
Der wincred.h-Header definiert CredUICmdLinePromptForCredentials als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code 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 |
|---|---|
| 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 |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für