RPC_HTTP_TRANSPORT_CREDENTIALS_V3_A structure (rpcdce.h)
The RPC_HTTP_TRANSPORT_CREDENTIALS_V3 structure defines additional credentials to authenticate to an RPC proxy server or HTTP proxy server when using RPC/HTTP.
RPC_HTTP_TRANSPORT_CREDENTIALS_V3 extends RPC_HTTP_TRANSPORT_CREDENTIALS_V2 by allowing arbitrary credential forms to be used.
Syntax
typedef struct _RPC_HTTP_TRANSPORT_CREDENTIALS_V3_A {
RPC_AUTH_IDENTITY_HANDLE TransportCredentials;
unsigned long Flags;
unsigned long AuthenticationTarget;
unsigned long NumberOfAuthnSchemes;
unsigned long *AuthnSchemes;
unsigned char *ServerCertificateSubject;
RPC_AUTH_IDENTITY_HANDLE ProxyCredentials;
unsigned long NumberOfProxyAuthnSchemes;
unsigned long *ProxyAuthnSchemes;
} RPC_HTTP_TRANSPORT_CREDENTIALS_V3_A, *PRPC_HTTP_TRANSPORT_CREDENTIALS_V3_A;
Members
TransportCredentials
A pointer to an opaque authentication handle in the form of an RPC_AUTH_IDENTITY_HANDLE structure.
Flags
A set of flags that can be combined with the bitwise OR operator.
AuthenticationTarget
Specifies the authentication target.
Should be set to one or both of the following values:
NumberOfAuthnSchemes
The number of elements in the AuthnScheme array.
AuthnSchemes
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.
ProxyCredentials
A pointer to an opaque authentication handle in the form of an RPC_AUTH_IDENTITY_HANDLE structure when authenticating against an HTTP proxy server. ProxyCredentials is only valid when AuthenticationTarget contains RPC_C_HTTP_AUTHN_TARGET_PROXY.
NumberOfProxyAuthnSchemes
The number of elements in the ProxyAuthnSchemes array when authenticating against an HTTP proxy server. NumberOfProxyAuthnSchemes is only valid when AuthenticationTarget contains RPC_C_HTTP_AUTHN_TARGET_PROXY.
ProxyAuthnSchemes
A pointer to an array of authentication schemes the client is willing to use when authenticating against an HTTP proxy server. Each element of the array can contain one of the following constants. ProxyAuthnSchemes is only valid when AuthenticationTarget contains RPC_C_HTTP_AUTHN_TARGET_PROXY.
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
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.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 7 [desktop apps only] |
| Minimum supported server | Windows Server 2008 R2 [desktop apps only] |
| Header | rpcdce.h (include Rpc.h) |
See also
RPC_HTTP_TRANSPORT_CREDENTIALS
RPC_HTTP_TRANSPORT_CREDENTIALS_V2