Функция ImpersonateSecurityContext (sspi.h)

Статья
08/26/2023

Функция ImpersonateSecurityContext позволяет серверу олицетворять клиента с помощью маркера, ранее полученного при вызове AcceptSecurityContext (General) или QuerySecurityContextToken. Эта функция позволяет серверу приложений действовать в качестве клиента, поэтому применяются все необходимые элементы управления доступом.

Синтаксис

KSECDDDECLSPEC SECURITY_STATUS SEC_ENTRY ImpersonateSecurityContext(
  [in] PCtxtHandle phContext
);

Параметры

[in] phContext

Дескриптор контекста для олицетворения. Этот дескриптор должен быть получен путем вызова функции AcceptSecurityContext (General).

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

Если функция завершается успешно, функция возвращает SEC_E_OK.

Если функция завершается сбоем, она возвращает следующий код ошибки.

Код возврата	Описание
SEC_E_INVALID_HANDLE	Дескриптор, переданный функции, недопустим.
SEC_E_NO_IMPERSONATION	Не удалось олицетворить клиента.
SEC_E_UNSUPPORTED_FUNCTION	Это значение возвращается режимом ядра Schannel, чтобы указать, что эта функция не поддерживается.

Серверное приложение вызывает функцию ImpersonateSecurityContext , когда ему необходимо олицетворять клиента. Перед этим сервер должен получить допустимый дескриптор контекста. Чтобы получить дескриптор контекста, сервер должен вызвать AcceptSecurityContext (General) для отправки входящего маркера безопасности клиента в систему безопасности. Сервер получает дескриптор контекста, если входящий контекст проверен. Функция создает маркер олицетворения и позволяет потоку или процессу выполняться с контекстом олицетворения.

При использовании поставщика поддержки безопасности Schannel серверное приложение должно передать флаг ASC_REQ_MUTUAL_AUTH при вызове AcceptSecurityContext (General) . Это гарантирует, что клиент будет запрашивать сертификат клиента во время подтверждения SSL/TLS. При получении сертификата клиента пакет Schannel проверяет сертификат клиента и пытается сопоставить его с учетной записью пользователя. При успешном сопоставлении создается маркер пользователя клиента, и эта функция завершается успешно.

Сервер приложений должен вызывать функцию RevertSecurityContext по завершении или при необходимости восстановления собственного контекста безопасности.

ImpersonateSecurityContext доступен не для всех пакетов безопасности на всех платформах. Как правило, он реализуется только на платформах и с пакетами безопасности, поддерживающими олицетворение. Чтобы узнать, поддерживает ли пакет безопасности олицетворение, вызовите функцию QuerySecurityPackageInfo .

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

Все функции олицетворения, включая ImpersonateSecurityContext , разрешают запрошенное олицетворение, если выполняется одно из следующих значений:

Запрошенный уровень олицетворения маркера меньше, чем SecurityImpersonation, например SecurityIdentification или SecurityAnonymous.
Вызывающий объект имеет привилегию SeImpersonatePrivilege .
Процесс (или другой процесс в сеансе входа в вызывающий объект) создал маркер, используя явные учетные данные с помощью функции LogonUser или LsaLogonUser .
Удостоверение, прошедшее проверку подлинности, совпадает с вызывающим.

Windows XP с пакетом обновления 1 (SP1) и более ранними версиями: Привилегия SeImpersonatePrivilege не поддерживается.

Windows XP: Привилегия SeImpersonatePrivilege не поддерживается до windows XP с пакетом обновления 2 (SP2).

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	sspi.h (включая Security.h)
Библиотека	Secur32.lib
DLL	Secur32.dll

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

AcceptSecurityContext (General)

QuerySecurityPackageInfo

RevertSecurityContext

Функции SSPI