The PsImpersonateClient routine causes a server thread to impersonate a client.
NTKERNELAPI NTSTATUS PsImpersonateClient( PETHREAD Thread, PACCESS_TOKEN Token, BOOLEAN CopyOnOpen, BOOLEAN EffectiveOnly, SECURITY_IMPERSONATION_LEVEL ImpersonationLevel );
Pointer to the server thread that is to impersonate the client.
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.
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.
Set to FALSE to allow the server to enable groups and privileges that are currently disabled in the client security context, TRUE otherwise.
A SECURITY_IMPERSONATION_LEVEL value that specifies the impersonation level at which the server is to access the token.
PsImpersonateClient returns STATUS_SUCCESS or an appropriate NTSTATUS value, such as the following:
||It was not possible to impersonate a client because of job restrictions.|
||There was insufficient memory to complete the operation.|
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.
|Windows version||Available in Windows XP and later versions of the Windows operating systems.|
|Header||ntifs.h (include Ntifs.h)|