PsImpersonateClient-Funktion (ntifs.h)

Die PsImpersonateClient-Routine bewirkt, dass ein Serverthread die Identität eines Clients ansah.

Syntax

NTSTATUS PsImpersonateClient(
  [in, out] PETHREAD                     Thread,
  [in]      PACCESS_TOKEN                Token,
  [in]      BOOLEAN                      CopyOnOpen,
  [in]      BOOLEAN                      EffectiveOnly,
  [in]      SECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Parameter

[in, out] Thread

Zeiger auf den Serverthread, der die Identität des Clients annehmen soll.

[in] Token

Zeiger auf das Token, das als Identitätswechseltoken zugewiesen werden soll. Dieses Token kann ein primäres Token oder ein Identitätswechseltoken sein. Legen Sie auf NULL fest, um den Identitätswechsel zu beenden.

[in] CopyOnOpen

Gibt an, ob das Token direkt geöffnet werden kann. Legen Sie auf TRUE fest, um anzugeben, dass das Token nicht direkt geöffnet werden kann. In diesem Fall muss das Token dupliziert und stattdessen das doppelte Token verwendet werden. Legen Sie auf FALSE fest, damit das Token direkt geöffnet werden kann.

[in] EffectiveOnly

Legen Sie diese Einstellung auf FALSE fest, damit der Server Gruppen und Berechtigungen aktivieren kann, die derzeit im Clientsicherheitskontext deaktiviert sind, andernfalls TRUE .

[in] ImpersonationLevel

Ein SECURITY_IMPERSONATION_LEVEL Wert, der die Identitätswechselebene angibt, auf der der Server auf das Token zugreifen soll.

Rückgabewert

PsImpersonateClient gibt STATUS_SUCCESS oder einen geeigneten NTSTATUS-Wert zurück, z. B. den folgenden:

Rückgabecode	Beschreibung
STATUS_ACCESS_DENIED	Es war aufgrund von Auftragseinschränkungen nicht möglich, die Identität eines Clients zu annehmen.
STATUS_NO_MEMORY	Es war nicht genügend Arbeitsspeicher vorhanden, um den Vorgang abzuschließen.

Hinweise

PsImpersonateClient bewirkt, dass der angegebene Serverthread die Identität des angegebenen Clients anniert.

Der Serverthread kann bereits die Identität eines Clients annehmen, wenn PsImpersonateClient aufgerufen wird. Wenn dies der Fall ist, wird die Verweisanzahl für das Token, das diesen Client darstellt, verringert. Um dieses Token für die spätere Verwendung beizubehalten, sollten Treiber Vor dem Aufrufen von PsImpersonateClientPsReferenceImpersonationToken aufrufen und den zeiger speichern, der von PsReferenceImpersonationToken zurückgegeben wird.

Um den neuen Identitätswechsel zu beenden und den Serverthread zum vorherigen Identitätswechsel zurückzugeben, rufen Sie PsImpersonateClient erneut auf, und übergeben Sie den gespeicherten Zeiger für den Tokenparameter . Um alle Identitätswechsel zu beenden, rufen Sie die PsRevertToSelf-Routine auf.

Andernfalls rufen Sie PsImpersonateClient erneut auf, um den Identitätswechsel zu beenden und den Serverthread in seinen ursprünglichen Sicherheitskontext zurückzugeben (d. h. den durch sein primäres Token dargestellten), und übergeben Sie einen NULL-Zeiger für den Token-Parameter .

Die PsImpersonateClient-Routine kann den Serverthread nicht erfolgreich an den vorherigen Identitätswechsel zurückgeben, wenn der Thread bereits die Identität angibt oder Auftragseinschränkungen vorliegen.

Die Routine stellt sicher, ob ein Clientidentitätswechsel tatsächlich auftreten kann, indem verschiedene Bedingungen überprüft werden, einschließlich der folgenden:

• Das vom Aufrufer übergebene Token verfügt nicht über eine anonyme Authentifizierungs-ID.
• Das Token des Prozesses, auf das vom Serverthread verwiesen wird, und das angegebene Token weisen die gleichen Sicherheits-IDs (SIDs) auf.
• Keines der Token ist eingeschränkt.

Wenn keine der Bedingungen erfüllt ist, erstellt die Routine eine Kopie des vorhandenen Tokens, das an den Aufruf übergeben wird, und weist das neu kopierte Token als Identitätswechseltoken zu, wenn auch mit eingeschränkter Sicherheitsidentitätswechselebene. Das heißt, der Serverthread kann nur Informationen zum Client abrufen. Wenn das Kopieren von Token nicht möglich ist, schlägt die Routine mit einem NTSTATUS-Code fehl.

Es ist äußerst unsicher, den Berechtigungsstatus eines nicht vertrauenswürdigen Benutzerthreads auszulösen (nehmen Sie z. B. den Thread eines Benutzers und annehmen Sie die Identität LocalSystem). Wenn für einen nicht vertrauenswürdigen Benutzerthread seine Berechtigungen ausgelöst wurden, kann der Benutzer das Threadtoken abrufen, nachdem es mit erhöhten Rechten versehen wurde, und die Sicherheit des gesamten Systems beeinträchtigen.

In Fällen, in denen ein höherer Berechtigungsstatus erforderlich ist, sollte die Aufgabe an eine Arbeitswarteschlange weitergeleitet werden, in der die Aufgabe sicher vom Systemworkerthread verarbeitet werden kann. Auf diese Weise ist kein Identitätswechsel erforderlich.

Die SeImpersonateClientEx-Routine kann verwendet werden, um zu bewirken, dass ein Thread die Identität eines Benutzers anwendet.

Weitere Informationen zur Sicherheit und Zugriffssteuerung finden Sie unter Windows-Sicherheitsmodell für Treiberentwickler und in der Dokumentation zu diesen Themen im Windows SDK.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP
Zielplattform	Universell
Header	ntifs.h (include Ntifs.h)
Bibliothek	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
DDI-Complianceregeln	HwStorPortProhibitedDIs(storport), PowerIrpDDis(wdm)

Weitere Informationen

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx