This topic has not yet been rated - Rate this topic

RPC_HTTP_TRANSPORT_CREDENTIALS structure

The RPC_HTTP_TRANSPORT_CREDENTIALS structure defines additional credentials to authenticate to an RPC proxy server when using RPC/HTTP.

Syntax

C++


typedef struct _RPC_HTTP_TRANSPORT_CREDENTIALS {
  SEC_WINNT_AUTH_IDENTITY  *TransportCredentials;
  unsigned long            Flags;
  unsigned long            AuthenticationTarget;
  unsigned long            NumberOfAuthnSchemes;
  unsigned long            *AuthnScheme;
  unsigned short __RPC_FAR *ServerCertificateSubject;
} RPC_HTTP_TRANSPORT_CREDENTIALS, *PRPC_HTTP_TRANSPORT_CREDENTIALS;

Members

TransportCredentials

A pointer to a SEC_WINNT_AUTH_IDENTITY structure that contains the user name, domain, and password for the user.

Flags

A set of flags that can be combined with the bitwise OR operator.

Value	Meaning
RPC_C_HTTP_FLAG_USE_SSL	Instructs RPC to use SSL to communicate with the RPC Proxy.
RPC_C_HTTP_FLAG_USE_FIRST_AUTH_SCHEME	When set, RPC chooses the first scheme in the AuthnSchemes array and attempts to authenticate to the RPC Proxy. If the RPC Proxy does not support the selected authentication scheme, the call fails. When not set, the RPC client queries the RPC Proxy for supported authentication schemes, and chooses one.

AuthenticationTarget

Specifies the authentication target. Should be set to one or both of the following values:

Value	Meaning
RPC_C_HTTP_AUTHN_TARGET_SERVER	Authenticate against the RPC Proxy, which is the HTTP Server from an HTTP perspective. This is the most common value.
RPC_C_HTTP_AUTHN_TARGET_PROXY	Authenticate against the HTTP Proxy. This value is uncommon.

NumberOfAuthnSchemes

The number of elements in the AuthnScheme array.

AuthnScheme

A pointer to an array of authentication schemes the client is willing to use. Each element of the array can contain one of the following constants:

RPC_C_HTTP_AUTHN_SCHEME_BASIC
RPC_C_HTTP_AUTHN_SCHEME_NTLM
RPC_C_HTTP_AUTHN_SCHEME_PASSPORT
RPC_C_HTTP_AUTHN_SCHEME_DIGEST
RPC_C_HTTP_AUTHN_SCHEME_NEGOTIATE

RPC_C_HTTP_AUTHN_SCHEME_PASSPORT, RPC_C_HTTP_AUTHN_SCHEME_NEGOTIATE and RPC_C_HTTP_AUTHN_SCHEME_DIGEST are defined as constants, but not currently supported. Callers should not specify them; doing so results in RPC_S_CANNOT_SUPPORT error. Each constant can be specified once. RPC does not verify this restriction for performance reasons, but specifying a constant more than once produces undefined results.

The algorithm for choosing the actual authentication scheme is as follows:

If RPC_C_HTTP_FLAG_USE_FIRST_AUTH_SCHEME is specified, the first authentication scheme is chosen. If it is not supported by the server, the connection establishment fails. If RPC_C_HTTP_FLAG_USE_FIRST_AUTH_SCHEME is not specified, the RPC client first attempts anonymous connection to the RPC Proxy. If IIS returns authentication challenge, the RPC client chooses the authentication scheme preferred by the server if it is also in the AuthnScheme array. If the scheme preferred by the server is not in the AuthnScheme array, the AuthnScheme array will be traversed from start to finish, and if a scheme is found that is also supported by the server, that authentication scheme is used.

ServerCertificateSubject

Contains an optional string with the expected server principal name. The principal name is in the same format as that generated for RpcCertGeneratePrincipalName (see Principal Names for more information). This member is used only when SSL is used. In such cases, the server certificate is checked against the generated principal name. If they do not match, an error is returned. This member enables clients to authenticate the RPC Proxy.

Remarks

If the TransportCredentials member is NULL and the authentication scheme is NTLM, the credentials of the currently logged on user are used. To avoid exposing user credentials on the network through a weak LM hash, user logon credentials are used only if one or both of the following conditions are true:

Caller requested use of SSL and used the ServerCertificateSubject member. This scenario guarantees credentials are protected both in transit and at the final destination, even if a weak hash is used.
The lncompatibilitylevel key is set to 2 or higher. This causes the NTLM security provider to emit or respond to only the strong NT hash, not the weak LM hash. In addition, customers are encouraged to use level 3 or higher, which will attempt NTLMv2.

If the Unicode version of the RpcBindingSetAuthInfoEx function is used, Unicode versions of the RPC_HTTP_TRANSPORT_CREDENTIALS and SEC_WINNT_AUTH_IDENTITY structures must also be provided, and the Flags member in TransportCredentials must be set to SEC_WINNT_AUTH_IDENTITY_UNICODE. If the ANSI version of the RpcBindingSetAuthInfoEx function is used, ANSI versions of RPC_HTTP_TRANSPORT_CREDENTIALS and SEC_WINNT_AUTH_IDENTITY structures must be provided, and the Flags member in TransportCredentials must be set to SEC_WINNT_AUTH_IDENTITY_ANSI.

Requirements

Minimum supported client	Windows XP with SP1 [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Header	Rpcdce.h (include Rpc.h)

Community Additions