CredUIPromptForCredentialsA-Funktion (wincred.h)
Die CredUIPromptForCredentials-Funktion erstellt und zeigt ein konfigurierbares Dialogfeld an, das Anmeldeinformationen von einem Benutzer akzeptiert.
Anwendungen, die auf Windows Vista oder Windows Server 2008 ausgerichtet sind, sollten aus den folgenden Gründen CredUIPromptForWindowsCredentials anstelle dieser Funktion aufrufen:
- CredUIPromptForWindowsCredentials ist mit der aktuellen Windows-Benutzeroberfläche konsistent.
- CredUIPromptForWindowsCredentials ist erweiterbarer und ermöglicht die Integration zusätzlicher Authentifizierungsmechanismen wie Biometrie und Smartcards.
- CredUIPromptForWindowsCredentials ist mit der Common Criteria-Spezifikation kompatibel.
Syntax
CREDUIAPI DWORD CredUIPromptForCredentialsA(
[in, optional] PCREDUI_INFOA pUiInfo,
[in] PCSTR pszTargetName,
[in] PCtxtHandle pContext,
[in, optional] DWORD dwAuthError,
[in, out] PSTR pszUserName,
[in] ULONG ulUserNameBufferSize,
[in, out] PSTR pszPassword,
[in] ULONG ulPasswordBufferSize,
[in, out] BOOL *save,
[in] DWORD dwFlags
);
Parameter
[in, optional] pUiInfo
Ein Zeiger auf eine CREDUI_INFO Struktur, die Informationen zum Anpassen der Darstellung des Dialogfelds enthält.
[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 (Distributed File System) weist diese Zeichenfolge die Form ServerName\ShareName auf. Dieser Parameter wird verwendet, um Zielinformationen beim Speichern und Abrufen von Anmeldeinformationen zu identifizieren.
[in] pContext
Dieser Parameter ist für die zukünftige Verwendung reserviert. Es muss NULL sein.
[in, optional] dwAuthError
Gibt an, warum das Dialogfeld "Anmeldeinformationen" benötigt wird. 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, kann das Dialogfeld den Benutzer auffordern, das Kennwort für das Konto zu ändern.
[in, out] pszUserName
Ein Zeiger auf eine NULL-endende Zeichenfolge, die den Benutzernamen für die Anmeldeinformationen enthält. Wenn eine Zeichenfolge ungleich null länge übergeben wird, wird die Option UserName des Dialogfelds mit der Zeichenfolge vorausgefüllt. Bei anderen Anmeldeinformationen als UserName/Password kann ein gemarshalltes Format der Anmeldeinformationen übergeben werden. Diese Zeichenfolge wird durch Aufrufen von CredMarshalCredential erstellt.
Diese Funktion kopiert den vom Benutzer bereitgestellten Namen in diesen Puffer, wobei maximal ulUserNameMaxChars-Zeichen kopiert werden. Dieses Format kann mithilfe von CredUIParseUsername in das Kennwortformat "UserName/" konvertiert werden. Ein gemarshalltes 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 Authentifizierungsfunktion wie WNetAddConnection oder eine SSP-Funktion übergeben werden.
Wenn keine Domäne oder kein Server als Teil dieses Parameters angegeben wird, wird der Wert des PszTargetName-Parameters als Domäne verwendet, um ein DomainName\UserName-Paar zu bilden. Bei der Ausgabe empfängt dieser Parameter eine Zeichenfolge, die das DomainName\UserName-Paar enthält.
[in] ulUserNameBufferSize
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 eine Zeichenfolge ungleich null für pszPassword angegeben wird, wird die Kennwortoption des Dialogfelds mit der Zeichenfolge vorab ausgefüllt.
Diese Funktion kopiert 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] save
Ein Zeiger auf eine BOOL , die den Anfangszustand des Kontrollkästchens Speichern angibt und den Status des Kontrollkästchens Speichern empfängt, nachdem der Benutzer auf das Dialogfeld geantwortet hat. Wenn dieser Wert nicht NULL ist und CredUIPromptForCredentials NO_ERROR zurückgibt, gibt pfSave den Zustand des Kontrollkästchens Speichern zurück, wenn der Benutzer im Dialogfeld OK ausgewählt hat.
Wenn das CREDUI_FLAGS_PERSIST-Flag angegeben ist, wird das Kontrollkästchen Speichern nicht angezeigt, sondern als aktiviert betrachtet.
Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag angegeben ist und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX nicht angegeben ist, wird das Kontrollkästchen Speichern nicht angezeigt, sondern als deaktiviert betrachtet.
Eine Anwendung, die CredUI verwenden muss, um den Benutzer zur Eingabe von Anmeldeinformationen aufzufordern, aber nicht die vom Anmeldeinformations-Manager bereitgestellten Dienste zur Verwaltung von Anmeldeinformationen benötigt, kann pfSave verwenden, um den Status des Kontrollkästchens Speichern zu erhalten, nachdem der Benutzer das Dialogfeld geschlossen hat. Dazu muss der Aufrufer CREDUI_FLAGS_DO_NOT_PERSIST und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX in dwFlags angeben. Wenn CREDUI_FLAGS_DO_NOT_PERSIST und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX festgelegt sind, ist die Anwendung für die Untersuchung von *pfSave verantwortlich, nachdem die Funktion zurückgegeben wurde. Wenn *pfSaveauf TRUE festgelegt ist, muss die Anwendung die entsprechende Aktion ausführen, um die Benutzeranmeldeinformationen in den Ressourcen der Anwendung zu speichern.
[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 |
|---|---|
|
Gibt an, dass eine Benutzeroberfläche angezeigt wird, auch 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. |
|
Füllen Sie das Kombinationsfeld mit der Aufforderung zur Eingabe eines Benutzernamens auf. |
|
Speichern Sie keine Anmeldeinformationen, oder zeigen Sie keine Kontrollkästchen an. Sie können CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX mit diesem Flag übergeben, um nur das Kontrollkästchen Speichern anzuzeigen, und das Ergebnis wird im ausgabeparameter pfSave zurückgegeben. |
|
Füllen Sie das Kombinationsfeld nur mit Benutzername/Kennwort auf. Zeigen Sie keine Zertifikate oder Smartcards im Kombinationsfeld an. |
|
Gibt an, dass der Aufrufer CredUIConfirmCredentials aufruft , nachdem er überprüft hat, ob die zurückgegebenen Anmeldeinformationen tatsächlich gültig sind. Dieser Mechanismus stellt sicher, dass ungültige Anmeldeinformationen nicht im Anmeldeinformations-Manager gespeichert werden. Geben Sie dieses Flag in allen Fällen an, es sei denn, CREDUI_FLAGS_DO_NOT_PERSIST wird angegeben. |
|
Betrachten Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen. |
|
Benachrichtigen Sie den Benutzer über unzureichende Anmeldeinformationen, indem Sie die Sprechblase "Anmeldung nicht erfolgreich" anzeigen. |
|
Lassen Sie dem Benutzer nicht zu, den angegebenen Benutzernamen zu ändern. |
|
Füllen Sie das Kombinationsfeld nur mit dem Kennwort aus. Lassen Sie die Eingabe eines Benutzernamens nicht zu. |
|
Das Kontrollkästchen Speichern wird nicht angezeigt, aber die Anmeldeinformationen werden so gespeichert, als ob das Kontrollkästchen angezeigt und aktiviert wäre. |
|
Füllen Sie das Kombinationsfeld nur mit lokalen Administratoren auf. Windows XP Home Edition: Dieses Flag filtert das bekannte Administratorkonto heraus. |
|
Füllen Sie das Kombinationsfeld nur mit Zertifikaten und Smartcards auf. Lassen Sie die Eingabe eines Benutzernamens nicht zu. |
|
Füllen Sie das Kombinationsfeld nur mit Zertifikaten oder Smartcards auf. Lassen Sie die Eingabe eines Benutzernamens nicht zu. |
|
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. |
|
Wenn das Kontrollkästchen aktiviert ist, zeigen Sie das Kontrollkästchen Speichern an, und geben Sie true im ausgabeparameter pfSave zurück. Andernfalls geben Sie FALSE zurück. Das Kontrollkästchen verwendet standardmäßig den Wert in pfSave . |
|
Bei den Anmeldeinformationen handelt es sich um "runas"-Anmeldeinformationen. Der Parameter TargetName gibt den Namen des Befehls oder Programms an, das bzw. das ausgeführt wird. Es wird nur zu Eingabeaufforderungszwecken verwendet. |
|
Überprüfen Sie, ob der Benutzername gültig ist. |
Rückgabewert
Der Rückgabewert ist ein DWORD und kann einer der folgenden Werte sein.
| Wert | BESCHREIBUNG |
|---|---|
|
Der Benutzer hat Abbrechen ausgewählt. Die Parameter pszUserName und pszPassword wurden nicht geändert. |
|
Diese status wird für alle ungültigen Flagkonfigurationen 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. Dieser Fehler wird in der Regel durch Aufrufen von CredUIPromptForCredentials und Übergeben des flags CREDUI_FLAGS_DO_NOT_PERSIST behandelt. |
|
Der Benutzer hat OK ausgewählt. Die Parameter pszUserName, pszPassword und pfSave geben die zuvor dokumentierten Werte zurück. |
Hinweise
Die CredUIPromptForCredentials-Funktion erstellt und zeigt ein modales Anwendungsdialogfeld an. Nachdem das Dialogfeld angezeigt wurde und bis es vom Benutzer oder der Anwendung geschlossen wird, kann kein anderes Fenster in der Anwendung aktiv werden.
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.
Ein X509-Zertifikat muss über den EKU-Wert ( Enhanced Key Usage, erweiterte Schlüsselverwendung ) szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2.2) verfügen, um angezeigt zu werden.
Windows XP: Dieser EKU-Wert ist nicht erforderlich, um X509-Zertifikate anzuzeigen.
Wenn CREDUI_FLAGS_GENERIC_CREDENTIALS nicht angegeben oder CREDUI_FLAGS_COMPLETE_USERNAME angegeben ist, wird der eingegebene Name syntaxgeprüft. Die Syntaxüberprüfung wendet die gleichen Regeln an, die von CredUIParseUserName angewendet 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 ist, wird das Kontrollkästchen Speichern angezeigt, und es steuert, ob die Anmeldeinformationen gespeichert 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.
- Für generische Anmeldeinformationen gibt es kein Authentifizierungspaket. Daher muss die Anwendung auf die Anmeldeinformationen zugreifen, um die Authentifizierung durchführen zu können. Zur Eingabe von Anmeldeinformationen auffordern, ohne CREDUI_FLAGS_ALWAYS_SHOW_UI vor der ersten Authentifizierung zu übergeben. Die Benutzeroberfläche wird nur angezeigt, wenn im Anmeldeinformations-Manager keine Anmeldeinformationen vorhanden sind. Bei allen nachfolgenden Nachrichten aus der Anwendung wird CREDUI_FLAGS_ALWAYS_SHOW_UI übergeben, da die Anmeldeinformationen im Anmeldeinformations-Manager für diese Ressource eindeutig ungültig sind.
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
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. Da Anmeldeinformationen nach Zielnamen gespeichert werden, kann ein bestimmter Benutzer nur über eine Anmeldeinformation pro Ziel im Anmeldeinformations-Manager verfügen.
Hinweis
Der wincred.h-Header definiert CredUIPromptForCredentials 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 |
|---|---|
| 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 |