PsImpersonateClient function

The PsImpersonateClient routine causes a server thread to impersonate a client.

Syntax

NTKERNELAPI NTSTATUS PsImpersonateClient(
  PETHREAD                     Thread,
  PACCESS_TOKEN                Token,
  BOOLEAN                      CopyOnOpen,
  BOOLEAN                      EffectiveOnly,
  SECURITY_IMPERSONATION_LEVEL ImpersonationLevel
);

Parameters

Thread

Pointer to the server thread that is to impersonate the client.

Token

Pointer to the token to be assigned as the impersonation token. This token can be a primary token or an impersonation token. Set to NULL to end the impersonation.

CopyOnOpen

Specifies whether the token can be opened directly. Set to TRUE to specify that the token cannot be opened directly. In this case, the token must be duplicated, and the duplicate token used instead. Set to FALSE to allow the token to be opened directly.

EffectiveOnly

Set to FALSE to allow the server to enable groups and privileges that are currently disabled in the client security context, TRUE otherwise.

ImpersonationLevel

A SECURITY_IMPERSONATION_LEVEL value that specifies the impersonation level at which the server is to access the token.

Return Value

PsImpersonateClient returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as the following:

Return code Description
STATUS_ACCESS_DENIED
It was not possible to impersonate a client because of job restrictions.
STATUS_NO_MEMORY
There was insufficient memory to complete the operation.

Remarks

PsImpersonateClient causes the specified server thread to impersonate the specified client.

The server thread could already be impersonating a client when PsImpersonateClient is called. If this is the case, the reference count on the token representing that client is decremented. To preserve this token for later use, drivers should call PsReferenceImpersonationToken before calling PsImpersonateClient and save the pointer that is returned by PsReferenceImpersonationToken.

To end the new impersonation and return the server thread to the previous impersonation, call PsImpersonateClient again, passing the saved pointer for the Token parameter. To end all impersonations, call the PsRevertToSelf routine.

Otherwise, to end the impersonation and return the server thread to its original security context (that is, the one represented by its primary token), call PsImpersonateClient again, passing a NULL pointer for the Token parameter.

The PsImpersonateClient routine can fail to successfully return the server thread to the previous impersonation if the thread is already impersonating or there are job restrictions.

It is extremely unsafe to raise the privilege state of an untrusted user thread (take a user's thread and impersonate LocalSystem, for example). If an untrusted user thread had its privilege raised, the user could grab the thread token after it has been elevated and subvert the security of the entire system.

In cases where a higher privilege state is required, the task should be dispatched to a work queue where the task can be safely handled by system worker thread . This way no impersonation is necessary.

The SeImpersonateClientEx routine can be used to cause a thread to impersonate a user.

For more information about security and access control, see the documentation on these topics in the Microsoft Windows SDK.

Requirements

   
Windows version Available in Windows XP and later versions of the Windows operating systems.
Target Platform Universal
Header ntifs.h (include Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL PASSIVE_LEVEL

See Also

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx