RpcGetAuthorizationContextForClient-Funktion (rpcasync.h)

  • Artikel

Die RpcGetAuthorizationContextForClient-Funktion gibt den Authz-Kontext für einen RPC-Client zurück, der mit Authz-Funktionen für die hochleistungsfähige Authentifizierung verwendet werden kann. Wird nur für ncalrpc - und ncacn_* -Protokollsequenzen unterstützt.

Syntax

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
);

Parameter

[in, optional] ClientBinding

Bindungshandle auf dem Server, das eine Bindung an einen Client darstellt. Der Server gibt die Identität des Clients an, der durch dieses Handle angegeben wird. Wenn ein Wert von 0 angegeben wird, gibt der Server die Identität des Clients an, der von diesem Serverthread bedient wird.

[in] ImpersonateOnReturn

Weist die Funktion an, bei der Rückgabe die Identität des Clients zu annehmen, und gibt dann eine AUTHZ_CLIENT_CONTEXT_HANDLE-Struktur zurück. Legen Sie diesen Parameter auf nonzero fest, um die Identität des Clients zu annehmen. Siehe Hinweise.

[in] Reserved1

Reserviert. Muss NULL sein.

[in, optional] pExpirationTime

Zeiger auf das Ablaufdatum und die Uhrzeit des Tokens. Wenn kein Wert übergeben wird, läuft das Token nie ab. Die Ablaufzeit wird derzeit nicht erzwungen.

[in] Reserved2

Reserviert. Muss eine LUID-Struktur sein, bei der jedes Element auf 0 festgelegt ist.

[in] Reserved3

Reserviert. Muss Null sein.

[in] Reserved4

Reserviert. Muss NULL sein.

[out] pAuthzClientContext

Zeiger auf eine AUTHZ_CLIENT_CONTEXT_HANDLE-Struktur , die direkt an Authz-Funktionen übergeben werden kann. Wenn die Funktion fehlschlägt, ist der Inhalt dieses Parameters nicht definiert.

Rückgabewert

Wert Bedeutung
RPC_S_OK
 Der Aufruf war erfolgreich.
RERROR_INVALID_PARAMETER
 Ein reservierter Parameter unterscheidet sich von seinem vorgeschriebenen Wert.
RPC_S_NO_CONTEXT_AVAILABLE
Der RPC-Client wurde nicht erfolgreich authentifiziert.
 

Fehler gibt einen RPC_S_*-Fehlercode oder einen Windows-Fehlercode zurück. Erweiterte Fehlerinformationen sind über standardmäßige RPC- oder Windows-Fehlercodeabrufmechanismen verfügbar. Eine Liste der gültigen Fehlercodes finden Sie unter RPC-Rückgabewerte.

Hinweise

Die RpcGetAuthorizationContextForClient-Funktion kann im gleichen Kontext wie die RpcImpersonateClient-Funktion aufgerufen werden. Alle Funktionen, die die Identität annehmen, überprüfen, ob der Aufrufer über das SeImpersonatePrivilege-Recht verfügt. Wenn der Aufrufer über das SeImpersonatePrivilege verfügt oder die authentifizierte Identität mit dem Aufrufer identisch ist, ist der angeforderte Identitätswechsel zulässig. Andernfalls ist der Identitätswechsel nur auf der Identifizierungsebene erfolgreich.

Hinweis Das SeImpersonatePrivilege-Recht wird erst unter Windows XP mit Service Pack 2 (SP2) unterstützt.

Die RpcGetAuthorizationContextForClient-Funktion wird nur für ncalrpc- und ncacn_*-Protokollsequenzen unterstützt und nicht für Named Pipes unterstützt, die nur Transportsicherheit implementieren.

Die RpcGetAuthorizationContextForClient-Funktion ist threadsicher und kann von mehreren Threads aufgerufen werden. Der in pAuthzClientContext zurückgegebene Kontext ist unabhängig vom Funktionsaufruf und kann nach seiner Fertigstellung verwendet werden. Der Aufrufer ist für das Freigeben des Kontexts durch einen Aufruf der RpcFreeAuthorizationContext-Funktion verantwortlich.

Leistungsverbesserungen, die durch die Verwendung der RpcGetAuthorizationContextForClient-Funktion im Vergleich zu früheren Methoden des Identitätswechsels oder der Zugriffsüberprüfung oder rückgängig machen zur Selbstverwaltung beobachtet werden, hängen von den folgenden Faktoren ab:

  • Wie oft die Funktion für eine bestimmte Clientidentität aufgerufen wird.
  • Protokollsequenz- und Identitätsnachverfolgung für den Funktionsaufruf.
Nachfolgende Aufrufe der RpcGetAuthorizationContextForClient-Funktion für dieselbe Clientidentität haben extrem niedrige Kosten. Diese Effizienz wird durch Ergebnisse früherer Anfragen erreicht, die zwischengespeichert wurden, und Antworten, die nach Möglichkeit aus dem Cache zurückgegeben werden.

Aufrufe über ncalrpc mit statischer Identitätsnachverfolgung führen die RpcGetAuthorizationContextForClient-Funktion schneller als Aufrufe über ncalrpc mit dynamischer Identitätsnachverfolgung aus. Aufrufe über ncacn_* werden für eine bestimmte Protokollsequenz ungefähr mit der gleichen Geschwindigkeit ausgeführt, unabhängig davon, ob die Identitätsnachverfolgung statisch oder dynamisch ist.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile rpcasync.h (include Rpc.h)
Bibliothek Rpcrt4.lib
DLL Rpcrt4.dll

Weitere Informationen

Client-/Server-Access Control-Funktionen

LUID

RPC-Rückgabewerte

RpcFreeAuthorizationContext

RpcImpersonateClient