3.2.6.1.2 TsProxyAuthorizeTunnel (Opnum 2)

  • Article

The TsProxyAuthorizeTunnel method is used to authorize the tunnel (2) based on rules defined by the RDG server. The RDG server SHOULD perform security authorization for the RDG client. The RDG server SHOULD<39> also use this method to require health checks from the RDG client, which SHOULD result in the RDG client performing health remediation.<40> After this method call has successfully been completed, a tunnel (2) shutdown can be performed. If there are existing channels within the tunnel, the RDG server MUST close all the channels before the tunnel shutdown. The tunnel (2) shutdown is accomplished by using the TsProxyCloseTunnel method call.

If this method call completes successfully, the ADM element Number of Connections MUST be incremented by 1.

Prerequisites: The connection MUST be in Connected state. If this call is made in any other state, the result is undefined.

Sequential Processing Rules:

  1. The RDG server MUST verify that the packetId field of the TSGPacket parameter is TSG_PACKET_TYPE_QUARREQUEST. Otherwise, it MUST return HRESULT_CODE(E_PROXY_NOTSUPPORTED).

  2. If the TSGPacket->TSGPacket.packetQuarRequest->dataLen is not zero and TSGPacket->TSGPacket.packetQuarRequest->data is not NULL, then the following.<41>

    • The RDG server MUST decode the SoH specified in TSGPacket->TSGPacket.packetQuarRequest->data with the RDG server certificate, which is encoded with one of PKCS #7 or X.509 encoding types, whichever is supported by the RDG server certificate. The RDG server MUST decrypt the SoH, which is encrypted using the Triple Data Encryption Standard algorithm.

    • If decoding of the SoH fails, the RDG server MUST return the error code returned by the cryptographic service provider.

    • If decoding of the SoH succeeds, the RDG server MUST also verify that the decoded message is prefixed with the Nonce. Otherwise, it MUST return ERROR_INVALID_PARAMETER.

    • The remaining bytes in the decoded message are the RDG client computer's statement of health response (SoHR).

  3. The RDG server MUST verify that the ADM element Number of Connections has not already reached the maximum number of connections configured by the RDG service. Otherwise, it MUST return the E_PROXY_MAXCONNECTIONSREACHED error code.

  4. The RDG server MUST do the user authorization as per policies configured at the RDG server. If the user is not authorized, it MUST return E_PROXY_NAP_ACCESS_DENIED.

  5. If quarantine is configured at the RDG server:<42>

    1. The RDG client computer's SoH SHOULD be passed to a Network Policy Server (NPS) using a RADIUS request. The statement of health is carried by the MS-Quarantine- SoH RADIUS attribute as specified in [MS-RNAP] section 2.2.1.19.

    2. After the NPS processes the statement of health request, a statement of health response is returned in a RADIUS response. The SoHR is encoded in the MS-Quarantine-SoH RADIUS attribute as specified in [MS-RNAP] section 2.2.1.19.

    3. The RDG server MUST sign the SoHR using SHA-1 hash and encode it with the RDG server certificate using PKCS #7 or X.509 encoding types, whichever is supported by the RDG server certificate and append the signed and encoded SoHR to TSGPacketResponse->TSGPacket.packetResponse->responseData, where TSGPacketResponse is an output parameter to TsProxyAuthorizeTunnel.

    4. If the RDG client computer's health is not compliant to quarantine settings:

      1. If the ADM element Reauthentication Connection is TRUE:

        1. The RDG server MUST find the original connection that has initiated the reauthentication using Reauthentication Tunnel Context and MUST set its ADM element Reauthentication Status to UserAuthorizationCompletedButQuarantineFailed.

        2. The RDG server MUST return the E_PROXY_QUARANTINE_ACCESSDENIED error code.

  6. If the ADM element Reauthentication Connection is TRUE:

    1. The RDG server MUST find the original connection which has initiated the reauthentication using Reauthentication Tunnel Context and MUST set its ADM element Reauthentication Status to UserAuthorizationCompleted.

  7. The RDG server MUST set the packetId member of the TSGPacketResponse out parameter to TSG_PACKET_TYPE_RESPONSE.

  8. The RDG server MUST increment the ADM element Number of Connections by 1.

  9. The RDG server MUST return ERROR_SUCCESS.

     HRESULT TsProxyAuthorizeTunnel(
   [in] PTUNNEL_CONTEXT_HANDLE_NOSERIALIZE tunnelContext,
   [in, ref] PTSG_PACKET TSGPacket,
   [out, ref] PTSG_PACKET* TSGPacketResponse
 );

tunnelContext: The RDG client MUST provide the RDG server with the same context handle it received from the TsProxyCreateTunnel method call. The RDG server SHOULD throw an exception if the RPC validation and verification fails.

TSGPacket: Pointer to the TSG_PACKET structure. The value of the packetId field MUST be set to TSG_PACKET_TYPE_QUARREQUEST. If this is set to any other value, the error E_PROXY_NOT_SUPPORTED is returned. The packetQuarRequest field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_QUARREQUEST structure.

TSGPacketResponse: Pointer to the TSG_PACKET structure. The value of the packetId field MUST be TSG_PACKET_TYPE_RESPONSE. The packetResponse field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_RESPONSE structure.

Return Values: The method MUST return ERROR_SUCCESS on success. Other failures MUST be one of the codes listed. The client MAY interpret failures in any way it deems appropriate. See 2.2.6 for details on these errors.

Return value

State transition

Description

ERROR_SUCCESS (0x00000000)

The connection MUST transition to the authorized state.

Returned when a call to the TsProxyAuthorizeTunnel method succeeds.

E_PROXY_NAP_ACCESSDENIED (0x800759DB)

The connection MUST transition to Tunnel Close Pending state.

Returned when the RDG server denies the RDG client access due to policy. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_NOTSUPPORTED) (0x000059E8)

The connection MUST transition to Tunnel Close Pending state.

Returned if the packetId field of the TSGPacket parameter is not TSG_PACKET_TYPE_QUARREQUEST. The RDG client MUST end the protocol when this error is received.

E_PROXY_QUARANTINE_ACCESSDENIED (0x800759ED)

The connection MUST transition to Tunnel Close Pending state.

Returned when the RDG server rejects the connection due to quarantine policy. The RDG client MUST end the protocol when this error is received.

ERROR_ACCESS_DENIED (0x00000005)

The connection MUST transition to Tunnel Close Pending state.

Returned when this call is made either in a state other than the Connected state or the tunnelContext parameter is NULL. The RDG client MUST end the protocol when this error is received.

HRESULT_CODE(E_PROXY_MAXCONNECTIONSREACHED) (0x59E6)

The connection MUST transition to end state.

Returned when the ADM element Number of Connections is equal to the maximum number of connections when the call is made.<43> The RDG client MUST end the protocol when this error is received.

ERROR_INVALID_PARAMETER (0x00000057)

The connection MUST not transition its state.

Returned when the Negotiated Capabilities ADM element contains TSG_NAP_CAPABILITY_QUAR_SOH and TSGPacket->TSGPacket.packetQuarRequest->dataLen is not zero and TSGPacket->TSGPacket.packetQuarRequest->data is not NULL and TSGPacket->TSGPacket.packetQuarRequest->data is not prefixed with Nonce.