ImpersonateNamedPipeClient-Funktion (namedpipeapi.h)

Artikel
08/25/2023

Die Funktion ImpersonateNamedPipeClient gibt die Identität einer Named-Pipe-Clientanwendung an.

Syntax

BOOL ImpersonateNamedPipeClient(
  [in] HANDLE hNamedPipe
);

Parameter

[in] hNamedPipe

Ein Handle für eine benannte Pipe.

Rückgabewert

Wenn die Funktion erfolgreich ist, ist der Rückgabewert ungleich Null.

Wenn die Funktion fehlerhaft ist, ist der Rückgabewert null. Um erweiterte Fehlerinformationen zu erhalten, rufen Sie GetLastError auf.

Hinweise

Mit der Funktion ImpersonateNamedPipeClient kann das Serverende einer Named Pipe die Identität des Clientendes annehmen. Wenn diese Funktion aufgerufen wird, ändert das Named-Pipe-Dateisystem den Thread des aufrufenden Prozesses , um den Identitätswechsel des Sicherheitskontexts der letzten aus der Pipe gelesenen Nachricht zu starten. Nur das Serverende der Pipe kann diese Funktion aufrufen.

Der Server kann die RevertToSelf-Funktion aufrufen, wenn der Identitätswechsel abgeschlossen ist.

Wichtig Wenn die ImpersonateNamedPipeClient-Funktion fehlschlägt, wird der Client nicht im Identitätswechsel ausgeführt, und alle nachfolgenden Clientanforderungen werden im Sicherheitskontext des Prozesses ausgeführt, der die Funktion aufgerufen hat. Wenn der aufrufende Prozess als privilegiertes Konto ausgeführt wird, kann er Aktionen ausführen, die der Client nicht ausführen darf. Um Sicherheitsrisiken zu vermeiden, sollte der aufrufende Prozess immer den Rückgabewert überprüfen. Wenn der Rückgabewert angibt, dass der Funktionsaufruf fehlgeschlagen ist, sollten keine Clientanforderungen ausgeführt werden.

Alle Identitätswechselfunktionen, einschließlich ImpersonateNamedPipeClient , lassen den angeforderten Identitätswechsel zu, wenn eine der folgenden Punkte zutrifft:

Die angeforderte Identitätswechselebene des Tokens ist kleiner als SecurityImpersonation, z. B. SecurityIdentification oder SecurityAnonymous.
Der Aufrufer verfügt über die Berechtigung SeImpersonatePrivilege .
Ein Prozess (oder ein anderer Prozess in der Anmeldesitzung des Aufrufers) hat das Token mithilfe expliziter Anmeldeinformationen über die LogonUser - oder LsaLogonUser-Funktion erstellt.
Die authentifizierte Identität ist identisch mit dem Aufrufer.

Windows XP mit SP1 und früher: Die SeImpersonatePrivilege-Berechtigung wird nicht unterstützt.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Überprüfen des Clientzugriffs mit ACLs.

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	namedpipeapi.h
Bibliothek	Advapi32.lib
DLL	Advapi32.dll