Freigeben über


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:

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.

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

[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.

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

[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
CREDUI_FLAGS_ALWAYS_SHOW_UI
0x00080
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.
CREDUI_FLAGS_COMPLETE_USERNAME
0x00800
Füllen Sie das Kombinationsfeld mit der Aufforderung zur Eingabe eines Benutzernamens auf.
CREDUI_FLAGS_DO_NOT_PERSIST
0x00002
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.
CREDUI_FLAGS_EXCLUDE_CERTIFICATES
0x00008
Füllen Sie das Kombinationsfeld nur mit Benutzername/Kennwort auf. Zeigen Sie keine Zertifikate oder Smartcards im Kombinationsfeld an.
CREDUI_FLAGS_EXPECT_CONFIRMATION
0x20000
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.
CREDUI_FLAGS_GENERIC_CREDENTIALS
0x40000
Betrachten Sie die vom Benutzer eingegebenen Anmeldeinformationen als generische Anmeldeinformationen.
CREDUI_FLAGS_INCORRECT_PASSWORD
0x00001
Benachrichtigen Sie den Benutzer über unzureichende Anmeldeinformationen, indem Sie die Sprechblase "Anmeldung nicht erfolgreich" anzeigen.
CREDUI_FLAGS_KEEP_USERNAME
0x100000
Lassen Sie dem Benutzer nicht zu, den angegebenen Benutzernamen zu ändern.
CREDUI_FLAGS_PASSWORD_ONLY_OK
0x00200
Füllen Sie das Kombinationsfeld nur mit dem Kennwort aus. Lassen Sie die Eingabe eines Benutzernamens nicht zu.
CREDUI_FLAGS_PERSIST
0x01000
Das Kontrollkästchen Speichern wird nicht angezeigt, aber die Anmeldeinformationen werden so gespeichert, als ob das Kontrollkästchen angezeigt und aktiviert wäre.
CREDUI_FLAGS_REQUEST_ADMINISTRATOR
0x00004
Füllen Sie das Kombinationsfeld nur mit lokalen Administratoren auf. Windows XP Home Edition: Dieses Flag filtert das bekannte Administratorkonto heraus.
CREDUI_FLAGS_REQUIRE_CERTIFICATE
0x00010
Füllen Sie das Kombinationsfeld nur mit Zertifikaten und Smartcards auf. Lassen Sie die Eingabe eines Benutzernamens nicht zu.
CREDUI_FLAGS_REQUIRE_SMARTCARD
0x00100
Füllen Sie das Kombinationsfeld nur mit Zertifikaten oder Smartcards auf. Lassen Sie die Eingabe eines Benutzernamens nicht zu.
CREDUI_FLAGS_SERVER_CREDENTIAL
0x04000
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.
CREDUI_FLAGS_SHOW_SAVE_CHECK_BOX
0x00040
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 .
CREDUI_FLAGS_USERNAME_TARGET_CREDENTIALS
0x80000
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.
CREDUI_FLAGS_VALIDATE_USERNAME
0x00400
Ü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
ERROR_CANCELLED
Der Benutzer hat Abbrechen ausgewählt. Die Parameter pszUserName und pszPassword wurden nicht geändert.
ERROR_INVALID_FLAGS
Diese status wird für alle ungültigen Flagkonfigurationen 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:
  • Der cbSize-Member muss ein Element sein.
  • Wenn der hbmBanner-Member nicht NULL ist, muss er vom Typ OBJ_BITMAP sein.
  • Wenn der pszMessageText-Member nicht NULL ist, darf er nicht größer als CREDUI_MAX_MESSAGE_LENGTH sein.
  • Wenn der pszCaptionText-Member nicht NULL ist, darf er nicht größer als CREDUI_MAX_CAPTION_LENGTH sein.
ERROR_NO_SUCH_LOGON_SESSION
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.
NO_ERROR
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

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.

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

Weitere Informationen

CredGetTargetInfo

CredMarshalCredential

CredUIConfirmCredentials

CredUIParseUserName

CredUIPromptForWindowsCredentials

CredUI_INFO

WNetAddConnection