IClientSecurity::SetBlanket

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This method sets the authentication information 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.

Syntax

HRESULT SetBlanket(
  IUnknown* pProxy,
  DWORD dwAuthnSvc,
  DWORD dwAuthzSvc,
  OLECHAR* pServerPrincName,
  DWORD dwAuthnLevel,
  DWORD dwImpLevel,
  RPC_AUTH_IDENTITY_HANDLE pAuthInfo,
  DWORD dwCapabilities 
);

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 can 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 standard 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 standard 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 standard security blanket negotiation algorithm.

• 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 standard 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 can 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 standard 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.

  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 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.

  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 standard 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_DEFAULT means COM will pick the capabilities using its standard security blanket negotiation 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 Value

• 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.

When 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 can be applied or only one can be applied.

Security information cannot be set on local interfaces such as the IClientSecurity interface. This interface is only supported locally. 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.

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 Windows 2000, 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.

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:

• The type of the authentication information depends on the authentication service DCOM chooses.
• 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 might get a security setting that will not work.

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

See Also

Reference

CoSetProxyBlanket
CoQueryProxyBlanket