Msv1_0SubAuthenticationFilter-Funktion (subauth.h)

Artikel
03/06/2024

Die Msv1_0SubAuthenticationFilter-Funktion führt eine Benutzeranmeldungsauthentifizierung durch, die für Domänencontroller spezifisch ist.

Die Funktion empfängt die Anmeldedaten des Benutzers und alle Informationen, die für den Benutzer in der SAM-Datenbank ( Security Accounts Manager ) des Domänencontrollers gefunden werden.

Diese Funktion wird von benutzerdefinierten Unterauthentifizierungspaket-DLLs für die Verwendung mit den Kerberos- und MSV1_0-Authentifizierungspaketen implementiert.

Syntax

NTSTATUS Msv1_0SubAuthenticationFilter(
  [in]  NETLOGON_LOGON_INFO_CLASS LogonLevel,
  [in]  PVOID                     LogonInformation,
  [in]  ULONG                     Flags,
  [in]  PUSER_ALL_INFORMATION     UserAll,
  [out] PULONG                    WhichFields,
  [out] PULONG                    UserFlags,
  [out] PBOOLEAN                  Authoritative,
  [out] PLARGE_INTEGER            LogoffTime,
  [out] PLARGE_INTEGER            KickoffTime
);

Parameter

[in] LogonLevel

Gibt die in LogonInformation angegebene Informationsebene an. Dieser Parameter ist normalerweise auf NetlogonInteractiveInformation festgelegt.

[in] LogonInformation

Ein Zeiger auf eine NETLOGON_LOGON_IDENTITY_INFO-Struktur . Mitglieder dieser Struktur enthalten Informationen über den Benutzer, der sich anmeldet. Das LogonDomainName-Element wird ignoriert.

[in] Flags

Optional. Enthält Flags, die die Umstände der Anmeldung beschreiben. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
MSV1_0_PASSTHRU	Passthrough-Authentifizierung Der Benutzer stellt keine Verbindung mit diesem Computer her.
MSV1_0_GUEST_LOGON	Dies ist ein Wiederholungsversuch der Anmeldung mithilfe des Gastkontos.

[in] UserAll

Ein Zeiger auf eine USER_ALL_INFORMATION-Struktur , die die Beschreibung des Benutzers enthält, wie er von der SAM-Datenbank zurückgegeben wird.

[out] WhichFields

Gibt die Elemente der USER_ALL_INFORMATION-Struktur zurück, die zurück in die SAM-Datenbank geschrieben werden müssen. Diese Member werden nur geschrieben, wenn Msv1_0SubAuthenticationFilter erfolgreich ist. Nur der folgende Wert ist gültig.

Wert	Bedeutung
USER_ALL_PARAMETERS	Schreiben Sie die im Parameter-Member der UserAll-Struktur enthaltenen Daten zurück in die SAM-Datenbank. Wenn die Größe des UNICODE_STRING Puffers des Parameters-Elements geändert wird, müssen Msv1_0SubAuthenticationFilter den Puffer mithilfe der MIDL_user_free-Funktion löschen und ihn mithilfe der funktion MIDL_user_allocate neu zuweisen.

[out] UserFlags

Werte, die von der LsaLogonUser-Funktion im ProfileBuffer-Parameter dieser Funktion zurückgegeben werden sollen. Dieser Parameter kann einen der folgenden Werte annehmen.

Wert	Bedeutung
LOGON_GUEST	Dies war eine Gastanmeldung.
LOGON_NOENCRYPTION	Der Aufrufer hat keine verschlüsselten Anmeldeinformationen angegeben.

Hinweis Gemäß der Konvention geben Unterauthentifizierungspakete Bits nur in der hohen Reihenfolge des UserFlags-Parameters zurück.

[out] Authoritative

Ein Zeiger auf einen booleschen Wert, der angibt, ob der zurückgegebene status eine autorisierende status ist, die an den ursprünglichen Aufrufer zurückgegeben werden soll. Wenn der zurückgegebene Wert FALSE ist, kann die Anmeldeanforderung auf einem anderen Domänencontroller erneut versucht werden. Dieser Parameter sollte unabhängig vom Rückgabewert des Funktionsaufrufs gültige Informationen zurückgeben. Dieser Parameter wird nicht mit dem Kerberos-Authentifizierungspaket verwendet.

[out] LogoffTime

Ein Zeiger auf einen Wert, der die Uhrzeit empfängt, zu der sich der Benutzer vom System abmelden soll. Diese Zeit wird verwendet, um die Anmeldedauer zu steuern, und wird als GMT-relative Windows-Systemzeit angegeben.

[out] KickoffTime

Ein Zeiger auf einen Wert, der die Uhrzeit empfängt, zu der der Benutzer vom System abgemeldet werden soll. Diese Zeit wird verwendet, um die Anmeldelebensdauer zu steuern, und wird als GMT-relative Systemzeit angegeben. Wenn der Benutzer nicht automatisch abgemeldet werden soll, geben Sie wie folgt einen großen positiven Wert an:

KickoffTime->HighPart = 0x7FFFFFFF;
KickoffTime->LowPart = 0xFFFFFFFF;

Rückgabewert

Diese Funktion muss einen der folgenden Werte zurückgeben.

Rückgabecode	Beschreibung
STATUS_SUCCESS	Es ist kein Fehler aufgetreten.
STATUS_ACCOUNT_DISABLED	Das Konto ist deaktiviert.
STATUS_ACCOUNT_EXPIRED	Das Konto ist abgelaufen.
STATUS_ACCOUNT_LOCKED_OUT	Das Konto ist gesperrt.
STATUS_INVALID_INFO_CLASS	LogonLevel ist ungültig.
STATUS_INVALID_LOGON_HOURS	Der Benutzer ist nicht berechtigt, sich zu diesem Zeitpunkt anzumelden.
STATUS_INVALID_WORKSTATION	Der Benutzer ist nicht autorisiert, sich bei der angegebenen Arbeitsstation anzumelden.
STATUS_NO_SUCH_USER	Der angegebene Benutzer verfügt über kein Konto.
STATUS_PASSWORD_EXPIRED	Das Kennwort ist abgelaufen.
STATUS_PASSWORD_MUST_CHANGE	Das Kennwort muss sich bei der nächsten Anmeldung ändern.
STATUS_WRONG_PASSWORD	Das Kennwort war ungültig.

Wenn die Msv1_0SubAuthenticationFilter-Funktion mit dem Kerberos-Authentifizierungspaket verwendet wird, wenn der Funktionsaufruf STATUS_SUCCESS zurückgibt und einer der beiden Parameter LogoffTime oder KickoffTime einen Wert ohne Zero aufweist, wird dieser Wert als Ticketlebensdauer verwendet. Wenn die Werte beider Parameter dagegen nichtzero sind, wird der kleinere dieser beiden Werte verwendet.

Wenn der Wert, der für die Ticketlebensdauer (früher von LogoffTime und KickoffTime) verwendet wird, größer als die Standardfahrscheinlebensdauer ist, wird dieser Wert als maximale Verlängerungszeit für das Ticket verwendet. Wenn hingegen der größere der beiden Werte (der spätere von LogoffTime und KickoffTime) kleiner als die Standard-Ticketlebensdauer ist, wird dieser Wert als Ticketlebensdauer verwendet. Weitere Informationen finden Sie unter Microsoft Kerberos.

Wenn diese Funktion einen Fehler zurückgibt, gibt das Key Distribution Center (KDC) bei Verwendung mit dem Kerberos-Authentifizierungspaket den Kerberos-Fehler KDC_ERR_POLICY mit dem wert status als erweiterten Fehlercode zurück.

Hinweise

Implementierungen dieser Funktion sollten keine Vorgänge ausführen, die LDAP-Datenverkehr ( Lightweight Directory Access Protocol ) verursachen. Stellen Sie beispielsweise keine Verbindung mit der Active Directory-Datenbank her, und fragen Sie sie nicht ab.

Nachdem das MSV1_0- oder Kerberos-Authentifizierungspaket eine Anmeldung überprüft hat, kann die Msv1_0SubAuthenticationFilter-Funktion eine zusätzliche Überprüfung durchführen, um zu bestimmen, ob sich ein Benutzer bei einem Netzwerkkonto anmelden kann. Diese Funktion wird aufgerufen, wenn die DLL des Unterauthentifizierungspakets ordnungsgemäß als "Auth0" in der Registrierung des Domänencontrollers registriert ist. Der Registrierungspfad unterscheidet sich je nachdem, ob sich die Funktion in einer MSV1_0- oder Kerberos-Subauthentication-Paket-DLL befindet.

Diese Filterroutine gibt möglicherweise STATUS_SUCCESS zurück, was angibt, dass die Anmeldung fortgesetzt werden soll, oder einen Fehlercode, der angibt, dass bei der zusätzlichen Überprüfung ein Fehler aufgetreten ist.

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	subauth.h

Freigeben über