3.2.6.1.1 TsProxyCreateTunnel (Opnum 1)

  • Article

The TsProxyCreateTunnel method sets up the tunnel (2) in which all further communication between the RDG client and the RDG server occurs. This is also used to exchange versioning and capability information between the RDG client and RDG server. It is used to exchange the RDG server certificate which has already been used to register for an authentication service. After this method call has successfully been completed, a tunnel (2) shutdown can be performed. This is accomplished by using the TsProxyCloseTunnel method call.

Prerequisites: The connection state MUST be in Start state.

Sequential Processing Rules:

  1. If any unexpected error occurs in the below process, the RDG server MUST return E_PROXY_INTERNALERROR.

  2. The RDG server MUST verify that a server authentication certificate is registered with SCHANNEL authentication service. Otherwise it MUST return E_PROXY_NOCERTAVAILABLE.

  3. If the RDG server is configured for pluggable authentication:

    1. The RDG server MUST verify that the packetId member of the TSGPacket parameter is either TSG_PACKET_TYPE_AUTH or TSG_PACKET_TYPE_REAUTH. Otherwise, it MUST return the E_PROXY_UNSUPPORTED_AUTHENTICATION_METHOD error code.

    2. If the packetId member of TSGPacket parameter is TSG_PACKET_TYPE_AUTH, then the RDG server MUST verify that TSGPacket->TSGPacket.packetAuth is not NULL and TSGPacket->TSGPacket.packetAuth->cookie is not NULL and TSGPacket->TSGPacket.packetAuth->cookieLen is not zero. Otherwise, it MUST return E_PROXY_COOKIE_BADPACKET. If the packetId member of the TSGPacket parameter is TSG_PACKET_TYPE_REAUTH, then the RDG server MUST verify that TSGPacket->TSGPacket.packetReauth->TSGInitialPacket.packetAuth is not NULL and TSGPacket->TSGPacket.packetReauth->TSGInitialPacket.packetAuth->cookie is not NULL and TSGPacket->TSGPacket.packetReauth->TSGInitialPacket.packetAuth->cookieLen is not zero. Otherwise, it MUST return E_PROXY_COOKIE_BADPACKET.

    3. The RDG server MUST authenticate the user using the cookie. If authentication fails, it MUST return E_PROXY_COOKIE_AUTHENTICATION_ACCESS_DENIED error code.

  4. If the RDG server is configured for RPC authentication:

    1. The RDG server MUST verify that the packetId member of the TSGPacket parameter type is either TSG_PACKET_TYPE_VERSIONCAPS or TSG_PACKET_TYPE_REAUTH. Otherwise, it MUST return the E_PROXY_INTERNALERROR error code.

  5. The RDG server MUST create a GUID and initialize the ADM element Nonce with it.

  6. The RDG server MUST create a unique identifier and initialize the ADM element Tunnel Id with it.

  7. If the packetId member of the TSGPacket parameter type is not TSG_PACKET_TYPE_REAUTH:

    1. The RDG server MUST initialize the ADM element Reauthentication Connection to FALSE.

    2. The RDG server MUST initialize the ADM element Reauthentication Status to NONE.

    3. The RDG server MUST initialize the ADM element Reauthentication Tunnel Context with a unique ULONGLONG identifier. This identifier MUST be used by the reauthentication connection to find this connection and set its Reauthentication Status ADM element.

  8. If the packetId member of the TSGPacket parameter is TSG_PACKET_TYPE_REAUTH:

    1. The RDG server MUST initialize the ADM element Reauthentication Connection to TRUE.

    2. The RDG server MUST not use the ADM element Reauthentication Status for this connection.

    3. The RDG server MUST initialize the ADM element Reauthentication Tunnel Context with TSGPacket->TSGPacket.packetReauth->tunnelContext.

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

  9. The RDG server MUST create a tunnel (2) context handle and MUST initialize the ADM element Tunnel Context Handle with it.

  10. The RDG server MUST initialize the ADM element Negotiated Capabilities with the common capabilities between the RDG client and the RDG server.

  11. If the RDG server supports the TSG_MESSAGING_CAP_CONSENT_SIGN capability and is configured to allow only a RDG client that supports the TSG_MESSAGING_CAP_CONSENT_SIGN capability, but the RDG client doesn't support the capability, then the RDG server MUST return the E_PROXY_CAPABILITYMISMATCH error.

  12. If the ADM element Negotiated Capabilities contains the TSG_MESSAGING_CAP_CONSENT_SIGN value, the packetId member of the TSGPacketResponse out parameter MUST be TSG_PACKET_TYPE_CAPS_RESPONSE. Otherwise, the packetId member of TSGPacketResponse MUST be TSG_PACKET_TYPE_QUARENC_RESPONSE.

  13. The RDG server SHOULD<36> set the certChainData field of TSG_PACKET_QUARENC_RESPONSE structure in TSGPacketResponse only when quarantine is configured at the RDG server and the ADM element Negotiated Capabilities contains TSG_NAP_CAPABILITY_QUAR_SOH.

  14. The RDG server MUST return ERROR_SUCCESS.

     HRESULT TsProxyCreateTunnel(
   [in, ref] PTSG_PACKET TSGPacket,
   [out, ref] PTSG_PACKET* TSGPacketResponse,
   [out] PTUNNEL_CONTEXT_HANDLE_SERIALIZE* tunnelContext,
   [out] unsigned long* tunnelId
 );

TSGPacket: Pointer to the TSG_PACKET structure. If this call is made for a reauthentication, then the packetId field MUST be set to TSG_PACKET_TYPE_REAUTH and the packetReauth field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_REAUTH structure. Otherwise, if this call is made for a new connection and the RDG server is configured for RPC authentication, then the value of the packetId field MUST be set to TSG_PACKET_TYPE_VERSIONCAPS and the packetVersionCaps field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_VERSIONCAPS structure. Otherwise, if this call is made for a new connection and the RDG server is configured for pluggable authentication <37>, then the value of the packetId field MUST be set to TSG_PACKET_TYPE_AUTH and the packetAuth field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_AUTH structure. If TSG_PACKET_AUTH is not populated correctly, the error E_PROXY_COOKIE_BADPACKET is returned.<38>

TSGPacketResponse: Pointer to the TSG_PACKET structure. If TSG_MESSAGING_CAP_CONSENT_SIGN capability is negotiated, the packetId member of the TSGPacketResponse out parameter MUST be TSG_PACKET_TYPE_CAPS_RESPONSE and the packetCapsResponse field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_CAPS_RESPONSE (section 2.2.9.2.1.7). Otherwise, the packetId member of TSGPacketResponse MUST be TSG_PACKET_TYPE_QUARENC_RESPONSE, and the packetQuarEncResponse field of the TSGPacket union field MUST be a pointer to the TSG_PACKET_QUARENC_RESPONSE structure. The ADM element Nonce MUST be initialized to a unique GUID and assigned to the nonce field of the TSG_PACKET_QUARENC_RESPONSE structure either in TSGPacketResponse->TSGPacket.packetQuarEncResponse or TSGPacketResponse->TSGPacket.packetCapsResponse->pktQuarEncResponse.

tunnelContext: An RPC context handle that represents context-specific information for the tunnel (2). The RDG server MUST provide a non-NULL value. The RDG client MUST save and use this context handle on all subsequent methods calls on the tunnel (2). The methods are TsProxyAuthorizeTunnel, TsProxyCreateChannel, and TsProxyCloseTunnel.

tunnelId: An unsigned long identifier representing the tunnel (2). The RDG server MUST save this value in the ADM element Tunnel id and SHOULD provide this value to the RDG client. The RDG client SHOULD save the tunnel id for future use on the RDG client itself. This tunnel id is not required on any future method calls to the RDG server; the tunnelContext is used instead.

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

Return value

State transition

Description

ERROR_SUCCESS (0x00000000)

The connection MUST transition to the connected state.

Returned when a call to the TsProxyCreateTunnel method succeeds.

E_PROXY_INTERNALERROR (0x800759D8)

The connection MUST transition to end state.

Returned when the server encounters an unexpected error. The RDG client MUST end the protocol when this error is received.

E_PROXY_COOKIE_BADPACKET (0x800759F7)

The connection MUST transition to end state.

Returned if the packetAuth field of the TSGPacket parameter is NULL.

E_PROXY_NOCERTAVAILABLE (0x800759EE)

The connection MUST transition to end state.

Returned when the RDG server cannot find a certificate to register for SCHANNEL Authentication Service (AS). The RDG client MUST end the protocol when this error is received.

E_PROXY_UNSUPPORTED_AUTHENTICATION_METHOD(0x800759F9)

The connection MUST transition to end state.

Returned to the RDG client when the RDG server is configured for pluggable authentication and the value of the packetId member of the TSGPacket parameter is not equal to TSG_PACKET_TYPE_AUTH or TSG_PACKET_TYPE_REAUTH. The RDG server MUST disconnect the connection.

E_PROXY_COOKIE_AUTHENTICATION_ACCESS_DENIED (0x800759F8)

The connection MUST transition to end state.

Returned when the given user does not have access to connect via RDG server. The RDG server MUST be in pluggable authentication mode for this error to be returned.

E_PROXY_CAPABILITYMISMATCH (0x800759E9)

The connection MUST transition to end state.

Returned when the RDG server supports the TSG_MESSAGING_CAP_CONSENT_SIGN capability and is configured to allow only a RDG client that supports the TSG_MESSAGING_CAP_CONSENT_SIGN capability, but the RDG client doesn't support the capability.