RPC_SECURITY_QOS structure (rpcdce.h)
The RPC_SECURITY_QOS structure defines security quality-of-service settings on a binding handle. See Remarks for version availability on Windows editions.
Syntax
typedef struct _RPC_SECURITY_QOS {
unsigned long Version;
unsigned long Capabilities;
unsigned long IdentityTracking;
unsigned long ImpersonationType;
} RPC_SECURITY_QOS, *PRPC_SECURITY_QOS;
Members
Version
Version of the RPC_SECURITY_QOS structure being used. This topic documents version 1 of the RPC_SECURITY_QOS structure. See RPC_SECURITY_QOS_V2, RPC_SECURITY_QOS_V3, RPC_SECURITY_QOS_V4 and RPC_SECURITY_QOS_V5 for other versions.
Capabilities
Security services being provided to the application. Capabilities is a set of flags that can be combined using the bitwise OR operator.
| Value | Meaning |
|---|---|
|
Used when no provider-specific capabilities are needed. |
|
Specifying this flag causes the RPC run time to request mutual authentication from the security provider. Some security providers do not support mutual authentication. If the security provider does not support mutual authentication, or the identity of the server cannot be established, a remote procedure call to such server fails with error RPC_S_SEC_PKG_ERROR.
Note RPC relies on the SSP to indicate which security options were successfully negotiated; RPC in turn fails any call for which the Security Service Provider (SSP) reports it could not negotiate an option. However, some security providers are known to report the successful negotiation of an option even when the option was not successfully negotiated. For example, NTLM will report successful negotiation of mutual authentication for backward compatibility reasons, even though it does not support mutual authentication. Check with the particular SSP being used to determine its behavior with respect to security options.
|
|
Not currently implemented. |
|
Accepts the client's credentials even if the certificate authority (CA) is not in the server's list of trusted CAs. This constant is used only by the SCHANNEL SSP. |
|
When specified, this flag directs the RPC runtime on the client to ignore an error to establish a security context that supports delegation. Normally, if the client asks for delegation and the security system cannot establish a security context that supports delegation, error RPC_S_SEC_PKG_ERROR is returned; when this flag is specified, no error is returned.
Note Unsupported on Windows XP and earlier client editions, unsupported on Windows 2000 and earlier server editions.
|
|
This flag specifies to RPC that the server is local to the machine making the RPC call. In this situation RPC instructs the endpoint mapper to pick up only endpoints registered by the principal specified in the ServerPrincName or Sid members (these members are available in RPC_SECURITY_QOS_V3, RPC_SECURITY_QOS_V4, and RPC_SECURITY_QOS_V5 only). See Remarks for more information.
Note Unsupported on Windows XP and earlier client editions, unsupported on Windows 2000 and earlier server editions.
|
|
If set, the RPC runtime uses the SChannel SSP to perform smartcard-based authentication without displaying a PIN prompt dialog box by the cryptographic services provider (CSP).
In the call to RpcBindingSetAuthInfoEx, the AuthIdentity parameter must be a SEC_WINNT_AUTH_IDENTITY structure whose members contain the following:
|
IdentityTracking
Sets the context tracking mode. Should be set to one of the values shown in the following table.
| Value | Meaning |
|---|---|
|
Security context is created only once and is never revised during the entire communication, even if the client side changes it. This is the default behavior if RPC_SECURITY_QOS is not specified. |
|
Context is revised whenever the ModifiedId in the client's token is changed. All protocols use the ModifiedId (see note).
Windows 2000: All remote protocols (all protocols other than ncalrpc) use the AuthenticationID, also known as the LogonId, to track changes in the client's identity. The ncalrpc protocol uses ModifiedId. |
ImpersonationType
Level at which the server process can impersonate the client.
| Value | Meaning |
|---|---|
|
Uses the default impersonation level. |
|
Client does not provide identification information to the server. The server cannot impersonate the client or identify the client. Many servers reject calls with this impersonation type.
Note Some security providers may treat this impersonation type as equivalent to RPC_C_IMP_LEVEL_IMPERSONATE. From the Windows security providers, this is done by RPC_C_AUTHN_WINNT only when used with protocol sequences other than ncalrpc. It is also done by RPC_C_AUTHN_GSS_NEGOTIATE, RPC_C_AUTHN_GSS_SCHANNEL and RPC_C_AUTHN_GSS_KERBEROS.
|
|
Server can obtain the client's identity, and impersonate the client to perform Access Control List (ACL) checks, but cannot impersonate the client. See Impersonation Levels for more information.
Note Some security providers may treat this impersonation type as equivalent to RPC_C_IMP_LEVEL_IMPERSONATE. From the Windows security providers, this is done by RPC_C_AUTHN_WINNT only when used with protocol sequences other than ncalrpc. It is also done by RPC_C_AUTHN_GSS_NEGOTIATE, RPC_C_AUTHN_GSS_SCHANNEL and RPC_C_AUTHN_GSS_KERBEROS.
|
|
Server can impersonate the client's security context on its local system, but not on remote systems. |
|
The server can impersonate the client's security context while acting on behalf of the client. The server can also make outgoing calls to other servers while acting on behalf of the client. The server may use the client's security context on other machines to access local and remote resources as the client. |
Remarks
The following listing defines the availability of QOS versions on various Windows operating systems:
- Version 1: Windows 2000 and later.
- Version 2: Windows XP with Service Pack 1 (SP1) and later.
- Version 3: Windows Server 2003 and later.
- Version 4: Windows Vista and later.
- Version 5: Windows 8 and later.
The client-side security functions RpcBindingInqAuthInfoEx and RpcBindingSetAuthInfo use the RPC_SECURITY_QOS structure to inquire about, or to set, the security quality of service for a binding handle.
RPC supports the RPC_C_QOS_CAPABILITIES_LOCAL_MA_HINT hint. This hint is used only when dynamic endpoints and mutual authentication are used. Furthermore, it is not supported for the ncadg_ protocol sequences. If this flag is used for a ncadg_ protocol sequence, or without using mutual authentication, RPC_S_INVALID_ARG is returned from the RpcBindingSetAuthInfoEx function call. This flag is designed to prevent a Denial of Service Attack. Using this flag forces the RPC Runtime to ask the endpoint mapper only for endpoints registered by the principal specified in the ServerPrincName or Sid members. This prevents an attacker on the local machine from trying to trick your RPC client to connect to a spoof endpoint it has registered in the endpoint mapper. Note that since the attack is local only (such as from a terminal server machine with many users), the flag also works only for RPC calls made locally.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Header | rpcdce.h (include Rpc.h) |