Sets the authentication information (the security blanket) that will be used to make calls on the specified proxy. This overrides the process default settings for the specified proxy. Calling this method changes the security values for all other users of the specified proxy.
HRESULT SetBlanket(
IUnknown * pProxy, //Indicates the interface proxy whose
// authentication information will be set
DWORD dwAuthnSvc, //The authentication service to use
DWORD dwAuthzSvc, //The authorization service to use
OLECHAR * pServerPrincName, //The server principal name to use with
// the authentication service
DWORD dwAuthnLevel, //The authentication level to use
DWORD dwImpLevel, //The impersonation level to use
RPC_AUTH_IDENTITY_HANDLE pAuthInfo,
//The identity of the client
DWORD dwCapabilities //The capability flags
);
For NTLMSSP or Kerberos, the structure is a SEC_WINNT_AUTH_IDENTITY_W or SEC_WINNT_AUTH_IDENTITY_EXW (on NT 5) structure. The client must ensure that the memory pointed to by this parameter remains valid and unchanged until a different identity is set on the proxy or until all proxies on the object are released.
For SSL, this value may be NULL or a CAPI (Crypto API) handle to a private certificate. If NULL is specified, the client is anonymous. If a CAPI handle is specified, the caller must not free it as long as any proxy to the object exists in the current apartment.
When using Snego, this parameter will be NULL or a pointer to a SEC_WINNT_AUTH_IDENTITY_EXW structure. If NULL, Snego will pick a list of authentication services to try based on those available on the client machine. If non-Null, the PackageList member of the structure must point to a comma-separated list of authentication service names. If PackageList is NULL, all calls using Snego will fail. The PackageListLength member indicates the number of bytes in the PackageList string.
If COLE_DEFAULT_AUTHINFO is specified, COM will pick the authentication information following its normal security blanket negotiation algorithm.
SetBlanket will return an error if both pAuthInfo is set and one of the cloaking flags is set in dwCapabilities.
IClientSecurity::SetBlanket sets the authentication information that will be used to make calls on the specified interface proxy. The values specified here override the values chosen by automatic security. Calling this method changes the security values for all other users of the specified proxy. If you want the changes to apply only to a particular instance of a proxy, call IClientSecurity::CopyProxy to make a private copy of the proxy and then call SetBlanket on the copy.
Whenever this method is called, DCOM will set the identity on the proxy, and future calls made using this proxy will use this identity. Calls in progress when SetBlanket is called will use the authentication information on the proxy at the time the call was started. If pAuthInfo is NULL, the proxy identity defaults to the current process token (unless an authentication identity was specified on a call to CoInitializeSecurity). See the Cloaking section to see how the cloaking flags affect the proxy when pAuthInfo is NULL.
By default, COM will choose the first available authentication service and authorization service available on both the client and server machines and the principal name that the server registered for that authentication service. Currently, COM will not try another authentication service if the first fails.
When the default constant for dwImpLevel is specified in SetBlanket, the parameter defaults to the value specified to CoInitializeSecurity. If CoInitializeSecurity is not called, it defaults to RPC_C_IMP_LEVEL_IDENTIFY.
The initial value for dwAuthnLevel on a proxy will be the higher of the value set on the client's call to CoInitializeSecurity and the server's call to CoInitializeSecurity. For any process that did not call CoInitializeSecurity, the default authentication level is RPC_C_AUTHN_CONNECT.
The default authentication and impersonation level for processes that do not call CoInitializeSecurity can be set with DCOMCNFG.
If EOAC_DEFAULT is specified for dwCapabilities, the valid capabilities from CoInitializeSecurity will be used. If CoInitializeSecurity was not called, EOAC_NONE will be used for the capabilities flag.
If SetBlanket is called simultaneously on two threads on the same proxy, only one set of changes will be applied. If SetBlanket and CRpcOptions::Set are called simultaneously on two threads on the same proxy, both changes may be applied or only one may be applied.
Security information cannot be set on local interfaces such as the IClientSecurity interface. However, since that interface is only supported locally, there is no need for security. IUnknown and IMultiQI are special cases. The location implementation makes remote calls to support these interfaces. SetBlanket can be used for IUnknown. IMultiQI will use the security settings on IUnknown. For more information, see IUnknown Security.
To change one SetBlanket parameter without having to deal with the others, one can specify the default constants for the other parameters. For example, on NT 5, the authentication service will generally be NTLMSSP on machine local proxies and Kerberos on machine remote proxies. Applications can change a parameter (such as the authentication level) and ignore the other parameters, including the authentication service, by setting all other parameters to the default constants. Note that it is important to set all unused parameters to the default constants because the default value is often not obvious. In particular, if you set the authentication service to the default, you should set the authentication information and principal name to the default. The reasons for this are twofold: First, the type of the authentication information depends on the authentication service DCOM chooses. Second, because DCOM needs to pass some complex authentication information for certain authentication services, if you set the authentication service to default and the authentication information to NULL, you may get a security setting that won't work.
The default parameters for SetBlanket and the SSL protocol are only valid in Windows NT 5.
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.
CoSetProxyBlanket, CoQueryProxyBlanket, RPC_C_AUTHN_xxx, RPC_C_AUTHZ_xxx, RPC_C_AUTHN_LEVEL_xxx, RPC_C_IMP_LEVEL_xxx, Setting Security at the Interface Proxy Level