Функция RpcGetAuthorizationContextForClient (rpcasync.h)

Статья
08/25/2023

Функция RpcGetAuthorizationContextForClient возвращает контекст Authz для клиента RPC, который можно использовать с функциями Authz для высокопроизводительной проверки подлинности. Поддерживается только для последовательностей протоколов ncalrpc и ncacn_* .

Синтаксис

RPC_STATUS RpcGetAuthorizationContextForClient(
  [in, optional] RPC_BINDING_HANDLE ClientBinding,
  [in]           BOOL               ImpersonateOnReturn,
  [in]           PVOID              Reserved1,
  [in, optional] PLARGE_INTEGER     pExpirationTime,
  [in]           LUID               Reserved2,
  [in]           DWORD              Reserved3,
  [in]           PVOID              Reserved4,
  [out]          PVOID              *pAuthzClientContext
);

Параметры

[in, optional] ClientBinding

Дескриптор привязки на сервере, представляющий привязку к клиенту. Сервер олицетворяет клиента, указанного этим дескриптором. Если указано нулевое значение, сервер олицетворяет клиента, обслуживаемого этим потоком сервера.

[in] ImpersonateOnReturn

Направляет функцию на олицетворения клиента при возврате, а затем возвращает AUTHZ_CLIENT_CONTEXT_HANDLE структуру. Присвойте этому параметру ненулевое значение, чтобы олицетворить клиента. См. заметки.

[in] Reserved1

Зарезервировано. Должно иметь значение NULL.

[in, optional] pExpirationTime

Указатель на дату и время окончания срока действия маркера. Если значение не передается, срок действия маркера не истечет. Время окончания срока действия в настоящее время не применяется.

[in] Reserved2

Зарезервировано. Должна быть структурой LUID , для каждого элемента которых задано значение 0.

[in] Reserved3

Зарезервировано. Должен равняться нулю.

[in] Reserved4

Зарезервировано. Должно иметь значение NULL.

[out] pAuthzClientContext

Указатель на структуру AUTHZ_CLIENT_CONTEXT_HANDLE , которую можно передать непосредственно в функции Authz. Если функция завершается сбоем, содержимое этого параметра не определено.

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

Значение	Значение
RPC_S_OK	Вызов выполнен успешно.
RERROR_INVALID_PARAMETER	Зарезервированный параметр отличается от предписанного значения.
RPC_S_NO_CONTEXT_AVAILABLE	Клиент RPC не прошел проверку подлинности.

Сбой возвращает код ошибки RPC_S_* или код ошибки Windows. Расширенные сведения об ошибке доступны через стандартные механизмы извлечения кода ошибки RPC или Windows. Список допустимых кодов ошибок см. в разделе Возвращаемые значения RPC.

Функция RpcGetAuthorizationContextForClient может вызываться в том же контексте, что и функция RpcImpersonateClient . Все функции, которые олицетворяют проверка, чтобы определить, имеет ли вызывающий объект привилегию SeImpersonatePrivilege. Если вызывающий объект имеет SeImpersonatePrivilege или если удостоверение, прошедшее проверку подлинности, совпадает с вызывающим, запрошенное олицетворение разрешено. В противном случае олицетворение будет успешно выполнено только на уровне Идентификация.

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

Функция RpcGetAuthorizationContextForClient поддерживается только для последовательностей протоколов ncalrpc и ncacn_* и не поддерживается в именованных каналов, которые реализуют только безопасность транспорта.

Функция RpcGetAuthorizationContextForClient является потокобезопасной и может вызываться из нескольких потоков. Контекст, возвращаемый в pAuthzClientContext , не зависит от вызова функции и может использоваться после его завершения. Вызывающий объект отвечает за освобождение контекста с помощью вызова функции RpcFreeAuthorizationContext .

Повышение производительности, наблюдаемое с помощью функции RpcGetAuthorizationContextForClient по сравнению с предыдущими методами олицетворения или доступа проверка или отменить изменения к себе, зависит от следующих факторов:

Сколько раз функция вызывается для заданного удостоверения клиента.
Последовательность протоколов и отслеживание удостоверений, которые действуют для вызова функции.

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

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

Требования

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