CoSetProxyBlanket

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function sets the authentication information that will be used to make calls on the specified proxy. This is a helper function for IClientSecurity::SetBlanket.

Syntax

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

Parameters

• pProxy
  [in] Indicates the 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, DCOM 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, DCOM will pick an authorization service following its normal security blanket negotiation algorithm. If you are using NTLMSSP or Kerberos for the authentication service, use RPC_C_AUTHZ_NONE for the authorization service.

• 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, DCOM will pick a principal name using its security blanket negotiation algorithm.

  If using Kerberos, this value must not be NULL. It must be the correct principal name of the server or the call will fail.

  Generally, specifying NULL will not reset server principal name on the proxy, rather, the previous setting will be retained.

  Exercise care when using NULL for pServerPrincName when selecting a different Authentication Service for the proxy. There is no guarantee that the previously set principal name will be valid for the newly selected Authentication Service.

• 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, DCOM will pick an authentication level following its normal security blanket negotiation algorithm.

  If this value is none, the authentication service must also be none.

• 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, DCOM will pick an impersonation level following its normal security blanket negotiation algorithm.

  If you are using NTLMSSP, this value must be RPC_C_IMP_LEVEL_IMPERSONATE or RPC_C_IMP_LEVEL_IDENTIFY.

• pAuthInfo
  [in] Pointer to an RPC_AUTH_IDENTITY_HANDLE value that establishes the identity of the client. This parameter is not used for calls on the same machine. It is authentication-service specific.

  If NULL is specified, DCOM uses the current proxy identity (which is either the process token or the impersonation token).

  If the handle refers to a structure, 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 SEC_WINNT_AUTH_IDENTITY.

  The client must ensure that the memory remains valid and unchanged until a different identity is set on the proxy or all proxies on the object are released.

  If COLE_DEFAULT_AUTHINFO is specified, DCOM will pick the authentication information following its normal security blanket negotiation algorithm.

  CoSetProxyBlanket 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_MUTUAL_AUTH is accepted, but has no effect.

  EOAC_DEFAULT means DCOM will pick the capabilities using its normal security blanket negotiation algorithm.

  EOAC_NONE indicates no capability flags are set.

  Either EOAC_STATIC_CLOAKING or EOAC_DYNAMIC_CLOAKING can be set if pAuthInfo is not set.

  If any capability flags other than those mentioned here are set, CoSetProxyBlanket will return an error.

Return Value

• S_OK
  Success.

• E_INVALIDARG
  One or more arguments is invalid.

Remarks

Sets the authentication information that will be used to make calls on the specified proxy.

The IClientSecurity::SetBlanket method and CoSetProxyBlanket function return an error if your application sets any of the following flags in the capabilities:

• EOAC_SECURE_REFS
• EOAC_ACCESS_CONTROL
• EOAC_APPID

This function encapsulates the following sequence of common calls (error handling excluded).

    pProxy->QueryInterface(IID_IClientSecurity, (void**)&pcs);
    pcs->SetBlanket(pProxy, dwAuthnSvc, dwAuthzSvc, pServerPrincName, 
        dwAuthnLevel, dwImpLevel, pAuthInfo, dwCapabilities);
    pcs->Release();

For more information about how to use this function, see the Remarks section of the IClientSecurity::SetBlanket method.

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

Requirements

See Also

Reference

COM Functions