[This is preliminary documentation and subject to change.]
Used by a server to help authenticate the client and to manage impersonation of the client.
When a client calls a server, the server can call CoGetCallContext to get a pointer to the IServerSecurity interface implemented on the call context object for the current method call. This pointer can be used to call an IServerSecurity method that allows the server to check the client's authentication or to impersonate the client.
The pointer to the instance of IServerSecurity returned by CoGetCallContext is automatically deleted when the server sends the reply back to the client. Therefore, the IServerSecurity object is valid only for the duration of the call. The IServerSecurity pointer must be released when it is no longer needed.
The stub management code in the system provides an implementation of IServerSecurity for objects by default as part of each incoming call, so typically you would not implement this interface.
You may choose to implement IServerSecurity on the custom stubs of objects that support custom marshaling to maintain a consistent programming model for their objects. Before dispatching an arriving call, custom marshallers call CoSwitchCallContext, specifying a new context object (which must implement IServerSecurity). The original call context must be restored after the server object sends a reply.
The methods of the IServerSecurity interface are called by a server object to examine the security settings of a particular call between a client and the server object (QueryBlanket) or to impersonate the client (ImpersonateClient and RevertToSelf). A server impersonates a client by running in the client's security context, which allows the server to test the privilege level of the calling client with an AccessCheck call and to access resources (such as files) as the client. For more information about how impersonation works, see Impersonation and Cloaking.
The information obtained through IServerSecurity also allows an object to perform security checks in addition to the automatic ACL checks COM performs. For example, an application may wish to allow time of day access to some objects or may have a different ACL for each method on an object.
IServerSecurity methods may be called only before the remote procedure call completes.
| IUnknown Methods | Description |
|---|---|
| QueryInterface | Returns pointers to supported interfaces. |
| AddRef | Increments the reference count. |
| Release | Decrements the reference count. |
| IServerSecurity Methods | Description |
| QueryBlanket | Called by the server to find out about the client that invoked one of its methods. |
| ImpersonateClient | Allows a server to impersonate a client for the duration of a call. |
| RevertToSelf | Restores the authentication information on a thread. |
| IsImpersonating | Indicates whether the server is currently impersonating the client. |
Windows NT: Use version 4.0 or later.
Windows: Use Windows 95 or later. Available as a redistributable for Windows 95.
Windows CE: Unsupported.
Header: Declared in objidl.h.
Security in COM, CoGetCallContext