IClientSecurity::SetBlanket

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

Parameters

pProxy

[in] Indicates the interface proxy to set.

dwAuthnSvc

[in] A single DWORD value from the list of RPC_C_AUTHN_xxx constants indicating the authentication service to use. It may be RPC_C_AUTHN_NONE if no authentication is required. If RPC_C_AUTHN_DEFAULT is specified, COM will pick an authentication service following its normal security blanket negotiation algorithm.

dwAuthzSvc

[in] A single DWORD value from the list of RPC_C_AUTHZ_xxx constants indicating the authorization service to use. If RPC_C_AUTHZ_DEFAULT is specified, COM will pick an authorization service following its normal security blanket negotiation algorithm. If you are using RPC_C_AUTHN_WINNT, use RPC_C_AUTHZ_NONE.

pServerPrincName

[in] Pointer to a WCHAR string that indicates the server principal name to use with the authentication service. If COLE_DEFAULT_PRINCIPAL is specified, COM will pick a principal name following its normal security blanket negotiation algorithm. For Windows NT 5.0, NTLMSSP supports the principal name on the same machine. If using Kerberos, this value must not be NULL. It must be the correct principal name of the server or calls to the server using this proxy will fail.

dwAuthnLevel

[in] A single DWORD value from the list of RPC_C_AUTHN_LEVEL_xxx constants indicating the authentication level to use. If RPC_C_AUTHN_LEVEL_DEFAULT is specified, COM will pick an authentication level following its normal security blanket negotiation algorithm. If this value is set to RPC_C_AUTHN_LEVEL_NONE, the authentication service must be RPC_C_AUTHN_NONE. Each authentication service may choose to use a more secure authentication level than the one specified.

dwImpLevel

[in] A single DWORD value from the list of RPC_C_IMP_LEVEL_xxx constants indicating the impersonation level to use. If RPC_C_IMP_LEVEL_DEFAULT is specified, COM will pick an impersonation level following its normal security blanket negotiation algorithm. If you are using NTLMSSP remotely, this value must be RPC_C_IMP_LEVEL_IMPERSONATE or RPC_C_IMP_LEVEL_IDENTIFY. When using NTLMSSP on the same machine, RPC_C_IMP_LEVEL_DELEGATE is also supported. When using SSL, this value must be RPC_C_IMP_LEVEL_IMPERSONATE. For Kerberos, this value can be RPC_C_IMP_LEVEL_IDENTIFY, RPC_C_IMP_LEVEL_IMPERSONATE, or RPC_C_IMP_LEVEL_DELEGATE.

pAuthInfo

[in] An RPC_AUTH_IDENTITY_HANDLE value that indicates the identity of the client. This parameter is not used for calls on the same machine. If pAuthInfo is NULL, COM uses the current proxy identity (which is either the process token, the impersonation token, or the authentication identity from CoInitializeSecurity). If the handle is not NULL, that identity is used. The format of the structure referred to by the handle depends on the provider of the authentication service.

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.

dwCapabilities

[in] A DWORD defining flags that specify the capabilities of this proxy. Capability flags are defined in the EOLE_AUTHENTICATION_CAPABILITIES enumeration. EOAC_NONE indicates no capability flags are set. EOAC_MUTUAL_AUTH is accepted, but has no effect. EOAC_ANY_AUTHORITY means COM will trust any SSL server certificate even if the top level certificate authority is not trusted. EOAC_DEFAULT means COM will pick the capabilities using its normal security blanket negotation algorithm. Either EOAC_STATIC_CLOAKING or EOAC_DYNAMIC_CLOAKING can be set if pAuthInfo is not set. (See Cloaking for more information). If any capability flags other than those mentioned here are indicated, SetBlanket will return an error.

Return Values

S_OK: Success.
E_INVALIDARG: One or more arguments is invalid.

Remarks

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.

QuickInfo

  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.