Функция PsImpersonateClient (ntifs.h)

Статья
03/08/2023

Подпрограмма PsImpersonateClient вызывает поток сервера для олицетворения клиента.

Синтаксис

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

Параметры

[in, out] Thread

Указатель на поток сервера для олицетворения клиента.

[in] Token

Указатель на маркер, назначаемый в качестве маркера олицетворения. Этот маркер может быть основным маркером или маркером олицетворения. Установите значение NULL , чтобы завершить олицетворение.

[in] CopyOnOpen

Указывает, можно ли открыть маркер напрямую. Задайте значение TRUE , чтобы указать, что маркер нельзя открыть напрямую. В этом случае маркер должен быть дублирован, а вместо него используется повторяющийся маркер. Задайте значение FALSE , чтобы разрешить открытие маркера напрямую.

[in] EffectiveOnly

Задайте значение FALSE , чтобы разрешить серверу включить группы и привилегии, которые в настоящее время отключены в контексте безопасности клиента. В противном случае — ЗНАЧЕНИЕ TRUE .

[in] ImpersonationLevel

Значение SECURITY_IMPERSONATION_LEVEL , указывающее уровень олицетворения, на котором сервер получает доступ к маркеру.

Возвращаемое значение

PsImpersonateClient возвращает STATUS_SUCCESS или соответствующее значение NTSTATUS, например следующее:

Код возврата	Описание
STATUS_ACCESS_DENIED	Невозможно было олицетворить клиента из-за ограничений задания.
STATUS_NO_MEMORY	Недостаточно памяти для завершения операции.

Поток сервера уже может олицетворять клиента при вызове PsImpersonateClient . В этом случае количество ссылок на маркер, представляющий этот клиент, уменьшается. Чтобы сохранить этот маркер для последующего использования, драйверы должны вызвать PsReferenceImpersonationToken перед вызовом PsImpersonateClient и сохранить указатель, возвращаемый PsReferenceImpersonationToken.

Чтобы завершить новое олицетворение и вернуть поток сервера в предыдущее олицетворение, вызовите PsImpersonateClient еще раз, передав сохраненный указатель для параметра Token . Чтобы завершить все олицетворения, вызовите подпрограмму PsRevertToSelf .

В противном случае, чтобы завершить олицетворение и вернуть поток сервера в исходный контекст безопасности (то есть в тот, который представлен его основным маркером), вызовите PsImpersonateClient еще раз, передав указатель NULL для параметра Token .

Подпрограмма PsImpersonateClient может не вернуть поток сервера в предыдущее олицетворение, если поток уже олицетворение или существуют ограничения задания.

Подпрограмма проверяет, может ли на самом деле происходить олицетворение клиента, проверяя различные условия, в том числе следующие:

Маркер, переданный вызывающим абонентом, не имеет анонимного идентификатора проверки подлинности
Маркер процесса, на который ссылается поток сервера, и заданный маркер имеют одинаковые идентификаторы безопасности (ИДЕНТИФИКАТОРЫ).
Ни тот из маркеров не ограничен

Если ни одно из условий не выполняется, подпрограмма создает копию существующего маркера, переданного в вызов, и назначает только что скопированный маркер в качестве маркера олицетворения, хотя и с ограниченным уровнем олицетворения безопасности; то есть поток сервера может получить только сведения о клиенте. Если копирование маркеров невозможно, подпрограмма завершается сбоем с кодом NTSTATUS.

Крайне небезопасно повышать состояние привилегий потока недоверенного пользователя (например, взять поток пользователя и олицетворить LocalSystem). Если ненадежный поток пользователя имеет повышенные привилегии, пользователь может получить маркер потока после его повышения и подорвать безопасность всей системы.

В случаях, когда требуется более высокий уровень привилегий, задача должна быть отправлена в рабочую очередь, где задача может быть безопасно обработана системным рабочим потоком . Таким образом, не требуется олицетворение.

Подпрограмму SeImpersonateClientEx можно использовать для вызова потока для олицетворения пользователя.

Дополнительные сведения о безопасности и управлении доступом см. в статье Модель безопасности Windows для разработчиков драйверов и в документации по этим темам в windows SDK.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP
Целевая платформа	Универсальное
Верхняя часть	ntifs.h (включая Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDDIs(storport), PowerIrpDDis(wdm)

См. также раздел

PsGetCurrentThread

PsReferenceImpersonationToken

PsRevertToSelf

SECURITY_IMPERSONATION_LEVEL

SeImpersonateClientEx