CoSetProxyBlanket

[This is preliminary documentation and subject to change.]

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

HRESULT CoSetProxyBlanket(
  IUnknown * pProxy,         //Indicates the proxy to set
  DWORD dwAuthnSvc,          //Authentication service to use
  DWORD dwAuthzSvc,          //Authorization service to use
  WCHAR * pServerPrincName,  //Server principal name to use with 
                             // the authentication service
  DWORD dwAuthnLevel,        //Authentication level to use
  DWORD dwImpLevel,          //Impersonation level to use
  RPC_AUTH_IDENTITY_HANDLE   pAuthInfo,
                             //Identity of the client
  DWORD dwCapabilities       //Capability flags
);
 

Parameter

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, Kerberos, or SSL 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. For SSL, this value must be one of the msstd or fullsic forms described in the SSL section of COM and Security Packages or NULL if you do not want mutual authentication..

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. SSL converts all authentication levels (except none) to encrypt.

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. In NT 5, NTLMSSP supports delegate-level impersonation on the same machine (RPC_C_IMP_LEVEL_DELEGATE). When using SSL, this value must be RPC_C_IMP_LEVEL_IMPERSONATE.

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 a SEC_WINNT_AUTH_IDENTITY_W or SEC_WINNT_AUTH_IDENTITY_EXW (on Windows NT 5) structure. The client must insure that the memory remains valid and unchanged until a different identity is set on th eproxy or 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. 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_ANY_AUTHORITY means DCOM will trust an SSL server certificate if the top level certificate authority is not trusted. EOAC_DEFAULT means DCOM will pick the capabilities using its normal security blanket negotation 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 Values

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 you set any of the following flags in the capabilities: EOAC_SECURE_REFS, EOAC_ACCESS_CONTROL, or 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.

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 objbase.h.
  Import Library: Included as a resource in ole32.dll.

See Also

IClientSecurity::SetBlanket, CoQueryClientBlanket, Security in COM, Setting Security at the Interface Proxy Level