rpcGetAuthorizationContextForClient 函式 (rpcasync.h)

發行項
03/01/2024

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 結構，且每個成員都設定為零。

[in] Reserved3

保留的。必須為零。

[in] Reserved4

保留的。必須是 Null。

[out] pAuthzClientContext

可直接傳遞至 Authz 函式 之AUTHZ_CLIENT_CONTEXT_HANDLE 結構的指標。如果函式失敗，則此參數的內容是未定義的。

傳回值

值	意義
RPC_S_OK	呼叫成功。
RERROR_INVALID_PARAMETER	保留的參數與其指定的值不同。
RPC_S_NO_CONTEXT_AVAILABLE	RPC 用戶端尚未成功驗證。

失敗會傳回RPC_S_* 錯誤碼或 Windows 錯誤碼。擴充錯誤資訊可透過標準 RPC 或 Windows 錯誤碼擷取機制取得。如需有效錯誤碼的清單，請參閱 RPC 傳回值。

備註

RpcGetAuthorizationContextForClient 函式可以在與 RpcImpersonateClient 函式相同的內容中呼叫。模擬檢查以判斷呼叫端是否有 SeImpersonatePrivilege 許可權的所有函式。如果呼叫端具有 SeImpersonatePrivilege，或已驗證的身分識別與呼叫端相同，則允許要求的模擬。否則，模擬只會在識別層級成功。

注意在 Windows XP Service Pack 2 (SP2) 之前，不支援 SeImpersonatePrivilege 許可權。

rpcGetAuthorizationContextForClient 函式僅支持 ncalrpc 和 ncacn_* 通訊協定序列，而且不支援僅實作傳輸安全性的命名管道。

RpcGetAuthorizationContextForClient 函式是安全線程，而且可以從多個線程呼叫。 pAuthzClientContext 中傳回的內容與函數調用無關，而且可以在完成之後使用。呼叫端負責釋放具有 RpcFreeAuthorizationContext 函式呼叫的內容。

相較於先前的模擬或存取檢查或還原為自我的方法，使用 RpcGetAuthorizationContextForClient 函式觀察到的效能改善，取決於下列因素：

針對指定的用戶端身分識別呼叫函式的次數。
函式調用生效的通訊協定序列和身分識別追蹤。

針對相同用戶端身分識別對 RpcGetAuthorizationContextForClient 函式的後續呼叫，成本非常低。這項效率是透過先前快取查詢的結果來達成，並盡可能從快取傳回回應。

透過具有靜態身分識別追蹤的 ncalrpc 呼叫會執行 RpcGetAuthorizationContextForClient 函式，比使用動態身分識別追蹤的 ncalrpc 呼叫更快。不論身分識別追蹤是靜態還是動態，透過ncacn_* 呼叫，都會以大約相同的速度執行指定通訊協定序列。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	rpcasync.h (包含 Rpc.h)
程式庫	Rpcrt4.lib
Dll	Rpcrt4.dll