CredUIPromptForCredentialsA-Funktion (wincred.h)
Die CredUIPromptForCredentials--Funktion erstellt und zeigt ein konfigurierbares Dialogfeld an, in dem Anmeldeinformationen von einem Benutzer akzeptiert werden.
Anwendungen, die auf Windows Vista oder Windows Server 2008 abzielen, sollten CredUIPromptForWindowsCredentials anstelle dieser Funktion aufrufen, aus folgenden Gründen:
- CredUIPromptForWindowsCredentials entspricht der aktuellen Windows-Benutzeroberfläche.
- CredUIPromptForWindowsCredentials ist erweiterbarer und ermöglicht die Integration zusätzlicher Authentifizierungsmechanismen wie Biometrie und Smartcards.
- CredUIPromptForWindowsCredentials ist mit der Spezifikation "Common Criteria" 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 mit Null beendete Zeichenfolge, die den Namen des Ziels für die Anmeldeinformationen enthält, in der Regel ein Servername. Bei DFS-Verbindungen (Distributed File System) ist diese Zeichenfolge der Form ServerName\ShareName-. 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" 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, kann das Dialogfeld den Benutzer auffordern, das Kennwort für das Konto zu ändern.
[in, out] pszUserName
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die den Benutzernamen für die Anmeldeinformationen enthält. Wenn eine nicht leere Zeichenfolge übergeben wird, wird die option UserName des Dialogfelds mit der Zeichenfolge vorgefüllt. Bei anderen Anmeldeinformationen als UserName/Passwordkann ein gemarstetes Format der Anmeldeinformationen übergeben werden. Diese Zeichenfolge wird durch Aufrufen von CredMarshalCredentialerstellt.
Mit dieser Funktion wird der vom Benutzer angegebene Name in diesen Puffer kopiert, wobei maximal ulUserNameMaxChars Zeichen kopiert werden. Dieses Format kann mithilfe CredUIParseUsernamein UserName/Password Format konvertiert werden. Ein marshalliertes 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 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 Parameter als Domäne verwendet, um ein DomainName-\UserName--Paar zu bilden. Bei der Ausgabe empfängt dieser Parameter eine Zeichenfolge, die DomainName\UserName Paar enthält.
[in] ulUserNameBufferSize
Die maximale Anzahl von Zeichen, die in pszUserName kopiert werden können, einschließlich des endierenden NULL-Zeichens.
[in, out] pszPassword
Ein Zeiger auf eine mit Null beendete Zeichenfolge, die das Kennwort für die Anmeldeinformationen enthält. Wenn für pszPassword-eine leere Zeichenfolge 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 wird. 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 endenden 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 Status 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, wird jedoch als aktiviert betrachtet.
Wenn das CREDUI_FLAGS_DO_NOT_PERSIST-Flag angegeben ist und CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX nicht angegeben wird, wird das Kontrollkästchen speichern nicht angezeigt, gilt jedoch als deaktiviert.
Eine Anwendung, die CredUI verwenden muss, um den Benutzer zur Eingabe von Anmeldeinformationen aufzufordern, die vom Anmeldeinformationsverwaltungs-Manager bereitgestellten Anmeldeinformationsverwaltungsdienste jedoch nicht 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 werden, ist die Anwendung für die Prüfung *pfSave nach dem Zurückgeben der Funktion verantwortlich, und wenn *pfSaveTRUEist, 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 ein bitweiserODER 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 Kennzeichen ist nur zulässig, wenn auch CREDUI_FLAGS_GENERIC_CREDENTIALS angegeben ist. |
|
Füllen Sie das Kombinationsfeld mit der Eingabeaufforderung für einen Benutzernamen auf. |
|
Speichern Sie keine Anmeldeinformationen, oder zeigen Sie Kontrollkästchen an. Sie können CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX mit dieser Kennzeichnung übergeben, um nur das Kontrollkästchen Speichern anzuzeigen, und das Ergebnis wird im pfSave Ausgabeparameter 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 überprüft wurde, ob die zurückgegebenen Anmeldeinformationen tatsächlich gültig sind. Mit diesem Mechanismus wird sichergestellt, dass ungültige Anmeldeinformationen nicht im Anmeldeinformations-Manager gespeichert werden. Geben Sie dieses Kennzeichen in allen Fällen an, es sei denn, CREDUI_FLAGS_DO_NOT_PERSIST ist angegeben. |
|
Berücksichtigen Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen. |
|
Benachrichtigen Sie den Benutzer über unzureichende Anmeldeinformationen, indem Sie den Sprechblasentipp "Anmelden nicht erfolgreich" anzeigen. |
|
Erlauben Sie dem Benutzer nicht, den angegebenen Benutzernamen zu ändern. |
|
Füllen Sie das Kombinationsfeld nur mit dem Kennwort auf. Die Eingabe eines Benutzernamens ist nicht zulässig. |
|
Zeigen Sie nicht das Kontrollkästchen Speichern an, aber die Anmeldeinformationen werden so gespeichert, als ob das Kontrollkästchen angezeigt und ausgewählt wurde. |
|
Füllen Sie das Kombinationsfeld nur mit lokalen Administratoren auf.Windows XP Home Edition: Dieses Kennzeichen filtert das bekannte Administratorkonto aus. |
|
Füllen Sie das Kombinationsfeld nur mit Zertifikaten und Smartcards auf. Die Eingabe eines Benutzernamens ist nicht zulässig. |
|
Füllen Sie das Kombinationsfeld nur mit Zertifikaten oder Smartcards auf. Die Eingabe eines Benutzernamens ist nicht zulässig. |
|
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. |
|
Wenn das Kontrollkästchen aktiviert ist, zeigen Sie das Kontrollkästchen Speichern an, und geben Sie TRUE- im pfSave Ausgabeparameter zurück, andernfalls geben Sie FALSE-zurück. Das Kontrollkästchen verwendet standardmäßig den Wert in pfSave-. |
|
Die Anmeldeinformationen sind "runas"-Anmeldeinformationen. Der parameter TargetName gibt den Namen des auszuführenden Befehls oder Programms an. Sie wird nur zu Aufforderungszwecken 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 Cancelausgewählt. Die parameter pszUserName und pszPassword parameter wurden nicht geändert. |
|
Dieser Status wird für alle ungültigen Flagkonfigurationen zurückgegeben. |
|
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:
|
|
Der Anmeldeinformations-Manager kann nicht verwendet werden. Normalerweise wird dieser Fehler behandelt, indem CredUIPromptForCredentials- aufgerufen und das CREDUI_FLAGS_DO_NOT_PERSIST-Flag übergeben wird. |
|
Der Benutzer hat OKausgewählt. Der pszUserName, pszPassword-und pfSave Parameter geben die zuvor dokumentierten Werte zurück. |
Bemerkungen
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 Kennzeichen 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.
Ein X509-Zertifikat muss über einen erweiterten Schlüsselverwendungswert (EKU) szOID_KP_SMARTCARD_LOGON (1.3.6.1.4.1.311.20.2.2) verfügen, der angezeigt werden soll.
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 wird, wird der eingegebene Name Syntaxüberprüft. Die Syntaxüberprüfung wendet dieselben Regeln an, wie sie von CredUIParseUserNameangewendet werden. 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 das Kontrollkästchen Speichern angezeigt, und es wird gesteuert, ob die Anmeldeinformationen gespeichert 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.
- Für generische Anmeldeinformationen gibt es kein Authentifizierungspaket. Daher muss die Anwendung auf die Anmeldeinformationen zugreifen, um die Authentifizierung durchzuführen. Aufforderung zur Eingabe von Anmeldeinformationen, nicht CREDUI_FLAGS_ALWAYS_SHOW_UI vor der ersten Authentifizierung übergeben. Die Benutzeroberfläche wird nur angezeigt, wenn im Anmeldeinformations-Manager keine Anmeldeinformationen vorhanden sind. Bei allen nachfolgenden Nachrichten innerhalb der Anwendung wird CREDUI_FLAGS_ALWAYS_SHOW_UI übergeben, da die Anmeldeinformationen im Anmeldeinformations-Manager für diese Ressource eindeutig nicht gültig sind.
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
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. Da Anmeldeinformationen anhand des Zielnamens gespeichert werden, kann ein bestimmter Benutzer nur über eine Anmeldeinformationen pro Ziel verfügen, die im Anmeldeinformations-Manager gespeichert sind.
Anmerkung
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 |
|---|---|
| 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 |