Export (0) Print
Expand All
COM
Expand Minimize

CoSetProxyBlanket 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(
  _In_      IUnknown *pProxy,
  _In_      DWORD dwAuthnSvc,
  _In_      DWORD dwAuthzSvc,
  _In_opt_  OLECHAR *pServerPrincName,
  _In_      DWORD dwAuthnLevel,
  _In_      DWORD dwImpLevel,
  _In_opt_  RPC_AUTH_IDENTITY_HANDLE pAuthInfo,
  _In_      DWORD dwCapabilities
);

Parameters

pProxy [in]

The proxy to be set.

dwAuthnSvc [in]

The authentication service to be used. For a list of possible values, see Authentication Service Constants. Use 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]

The authorization service to be used. For a list of possible values, see Authorization Constants. If RPC_C_AUTHZ_DEFAULT is specified, DCOM will pick an authorization service following its normal security blanket negotiation algorithm. RPC_C_AUTHZ_NONE should be used as the authorization service if NTLMSSP, Kerberos, or Schannel is used as the authentication service.

pServerPrincName [in, optional]

The server principal name to be used with the authentication service. If COLE_DEFAULT_PRINCIPAL is specified, DCOM will pick a principal name using its security blanket negotiation algorithm. If Kerberos is used as the authentication service, this value must not be NULL. It must be the correct principal name of the server or the call will fail.

If Schannel is used as the authentication service, this value must be one of the msstd or fullsic forms described in Principal Names, or NULL if you do not want mutual authentication.

Generally, specifying NULL will not reset the server principal name on the proxy; rather, the previous setting will be retained. You must be careful when using NULL as pServerPrincName when selecting a different authentication service for the proxy, because there is no guarantee that the previously set principal name would be valid for the newly selected authentication service.

dwAuthnLevel [in]

The authentication level to be used. For a list of possible values, see Authentication Level Constants. 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]

The impersonation level to be used. For a list of possible values, see Impersonation Level Constants. If RPC_C_IMP_LEVEL_DEFAULT is specified, DCOM will pick an impersonation level following its normal security blanket negotiation algorithm. If NTLMSSP is the authentication service, this value must be RPC_C_IMP_LEVEL_IMPERSONATE or RPC_C_IMP_LEVEL_IDENTIFY. NTLMSSP also supports delegate-level impersonation (RPC_C_IMP_LEVEL_DELEGATE) on the same computer. If Schannel is the authentication service, this parameter must be RPC_C_IMP_LEVEL_IMPERSONATE.

pAuthInfo [in, optional]

A pointer to an RPC_AUTH_IDENTITY_HANDLE value that establishes the identity of the client. The format of the structure referred to by the handle depends on the provider of the authentication service.

For calls on the same computer, RPC logs on the user with the supplied credentials and uses the resulting token for the method call.

For NTLMSSP or Kerberos, the structure is a SEC_WINNT_AUTH_IDENTITY or SEC_WINNT_AUTH_IDENTITY_EX structure. The client can discard pAuthInfo after calling the API. RPC does not keep a copy of the pAuthInfo pointer, and the client cannot retrieve it later in the CoQueryProxyBlanket method.

If this parameter is NULL, 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.

For Schannel, this parameter must be either a pointer to a CERT_CONTEXT structure that contains the client's X.509 certificate or is NULL if the client wishes to make an anonymous connection to the server. If a certificate is specified, the caller must not free it as long as any proxy to the object exists in the current apartment.

For Snego, this member is either NULL, points to a SEC_WINNT_AUTH_IDENTITY structure, or points to a SEC_WINNT_AUTH_IDENTITY_EX structure. If it is NULL, Snego will pick a list of authentication services based on those available on the client computer. If it points to a SEC_WINNT_AUTH_IDENTITY_EX structure, the structure's PackageList member must point to a string containing a comma-separated list of authentication service names and the PackageListLength member must give the number of bytes in the PackageList string. If PackageList is NULL, all calls using Snego will fail.

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

CoSetProxyBlanket will fail if pAuthInfo is set and one of the cloaking flags is set in the dwCapabilities parameter.

dwCapabilities [in]

The capabilities of this proxy. For a list of possible values, see the EOLE_AUTHENTICATION_CAPABILITIES enumeration. The only flags that can be set through this function are EOAC_MUTUAL_AUTH, EOAC_STATIC_CLOAKING, EOAC_DYNAMIC_CLOAKING, EOAC_ANY_AUTHORITY (this flag is deprecated), EOAC_MAKE_FULLSIC, and EOAC_DEFAULT. Either EOAC_STATIC_CLOAKING or EOAC_DYNAMIC_CLOAKING can be set if pAuthInfo is not set and Schannel is not the authentication service. (See Cloaking for more information.) If any capability flags other than those mentioned here are set, CoSetProxyBlanket will fail.

Return value

This function can return the following values.

Return codeDescription
S_OK

The function was successful.

E_INVALIDARG

One or more arguments is invalid.

 

Remarks

CoSetProxyBlanket sets the authentication information that will be used to make calls on the specified proxy. 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();

This sequence calls QueryInterface on the proxy to get a pointer to IClientSecurity, and with the resulting pointer, calls IClientSecurity::SetBlanket and then releases the pointer.

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

Objbase.h

Library

Ole32.lib

DLL

Ole32.dll

See also

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

 

 

Community Additions

ADD
Show:
© 2014 Microsoft