

PCoIP Connection Broker Protocol Structure¶

Broker Protocol messages are XML messages embedded in the body-content of HTTP messages, using a strict client/server or API message flow where the PCoIP client is the ‘client’ and the broker is the ‘server’.

Protocol structure layers

The Broker Protocol uses HTTP encrypted by Transport Layer Security (TLS) as the transport mechanism to deliver messages. To ensure secure delivery of the Broker Protocol messages, specific aspects of the TLS and HTTP layers are specified.

To provide solution flexibility in a compatible way, most messages provide mechanisms for name-spaced optional variables to be tunneled between components.

Localization in the Broker Protocol is handled from the server end so the broker is responsible for creating messages in the languages it wishes to support.

Security Requirements¶

For security and interoperability, all sessions are secured over TLS 1.0 or above with a specified preferred cipher suite. Broker Protocol session metadata (cookie) handling is also specified to ensure uniform operation across the platform.

Broker Protocol HTTP Overview¶

All requests to and from the Broker Protocol are initiated by the HTTP client endpoint.

The Broker Protocol makes use of the following HTTP elements and functionality to transport the Broker Protocol messages:

HTTP version: 1.1
HTTP Requests: POST
HTTP Responses: 200 OK and error responses
https-URI: https://<FQDN or ip-address>/pcoip-broker/xml
HTTP header content-type: application/xml charset=UTF-8
Fixed-length or chunked HTTP payload
Persistent and/or non-persistent HTTP connection
X-Forwarded-For header
Client-Log-Id header

As well, the Broker Protocol makes use of an HTTP cookie called JSESSIONID as per RFC 6265.

Broker Protocol Application (XML) Layer¶

Requests and responses are paired as much as possible with, for example, a client sending an <example> request and the server responding with an <example-resp> response. Each request-response pair is considered a message transaction. Only a single message transaction may be outstanding at any point in time for each Broker Protocol session.

The Broker Protocol messages broadly fit into the following categories:

Negotiate protocol version and capabilities (required)
Authenticate the user (basic password required)
Present the user with their inventory (required)
Start a session (required)
Perform operations on resources or machines (optional)
Terminate the brokering session (optional)
Broker Protocol application layer errors are indicated by sending an <error-resp> message towards the client.

Many flows and messages are optional. A standard flow that is required is a negotiate, authenticate, select and start session flow. See Overview of PCoIP Session Initiation Broker Protocol Messages provides an example of this flow.

Broker Protocol Session States¶

A Broker Protocol session is created when the <hello> message has been successfully processed and a JSESSIONID has been generated. The following diagramshows the state transition diagram for the Broker Protocol session.

Broker protocol session states

State transition diagram for the Broker Protocol session¶

As shown in the preceding figure, the Broker Protocol session has four states:

CREATED: The session transitions into the CREATED state after successfully processing a <hello> request. A JSESSIONID value is generated when the session enters this state.
AUTHENTICATED: The session transitions into the AUTHENTICATED state after successfully authenticating a user (after receiving an <authenticate-resp> message with AUTH_SUCCESSFUL_AND_COMPLETE result).
ALLOCATED: The session transitions into the ALLOCATED state after successfully allocating a resource (after receiving an <allocate-resource-resp> message with ALLOC_SUCCESSFUL result).
ERRORED: The session transitions into the ERRORED state after detecting an error and sending an <error-resp> message.

The Broker Protocol session terminates when a <bye> message has been processed or when the maximum session time elapses. The JSESSIONID is deleted/invalidated when the session terminates.

Overview of PCoIP Session Initiation Broker Protocol Messages¶

The following diagram shows the typical Broker Protocol messages exchanged between the PCoIP Connection Manager and a broker to initiate a PCoIP session.

Broker protocol messages

Typical message transactions to launch a PCoIP session¶

The PCoIP client and PCoIP Connection Manager exchange an almost identical set of messages. The PCoIP client initiates the Broker Protocol session by sending a <hello> request to the PCoIP Connection Manager. In this example, the PCoIP client authenticates the user using the username and password. Here are the steps to initiate/broker a PCoIP session:

The PCoIP Connection Manager, triggered by the client, initiates a Broker Protocol session by sending a <hello> request message. The connection broker responds with the <hello-resp> response message. The <hello-resp> message contains the AUTHENTICATE_VIA_PASSWORD method which tells the client to authenticate the user via the username and password.
The PCoIP Connection Manager sends an <authenticate> message and specifies "password" as the authentication method. The <authenticate method="password"> message contains the username, domain, and password entered by the user. The connection broker responds with the <authenticate-resp> message and specifies AUTH_SUCCESSFUL_AND_COMPLETE.
The PCoIP Connection Manager sends the <get-resource-list> message to request the list of resources to which the authenticated user is entitled and the broker returns the list of the resources.
The PCoIP Connection Manager sends the <allocate-resource> message to launch a PCoIP session to the specified resource (desktop) and the connection broker responds with the <allocate-resource-resp> response messages and specifies ALLOC_SUCCESSFUL.

Example Broker Protocol Messages¶

The following sections provide example messages between the PCoIP Connection Manager and the connection broker for the flow shown in the preceding diagram. The parameters marked as 'xxxx' would need to be filled in during an actual message exchange.

hello message¶

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<hello>
   <client-info>
      <product-name>Teradici Windows Soft Client</product-name>
      <product-version>3.1.5</product-version>
      <platform>Windows 7 64-bit</platform>
      <locale>en_US</locale>
      <hostname>my-client.teradici.local</hostname>
      <serial-number>123456</serial-number>
      <device-name>some-name</device-name>
   </client-info>
   <pcm-info>
      <product-name>Teradici PCoIP Connection Manager</product-name>
      <product-version>1.0.0.12345</product-version>
      <platform>Ubuntu 14.4 64-bit</platform>
      <ip-address>10.0.136.93</ip-address>
      <hostname>cm1.example.com</hostname>
   </pcm-info>
</hello>
</pcoip-broker>

hello-resp message¶

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<hello-resp>
   <brokers-info>
      <broker-info>
         <product-name>XYZ Broker</product-name>
         <product-version>5.1.0</product-version>
         <platform>Linux Ubuntu 10.4 64-bit</platform>
         <locale>en_US</locale>
         <ip-address>10.0.136.26</ip-address>
         <hostname>broker1.teradici.com</hostname>
      </broker-info>
   </brokers-info>
   <next-authentication>
      <authentication-methods>
         <method>AUTHENTICATE_VIA_PASSWORD</method>
      </authentication-methods>
      <domains>
         <domain>domain-1</domain>
         <domain>domain-2</domain>
      </domains>
   </next-authentication>
</hello-resp>
</pcoip-broker>

authenticate message¶

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Cookie: JSESSIONID=aabbccddeeff00112233445566778899<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<authenticate method="password" >
   <username>username</username> 
   <password>password</password>
   <domain>domain</domain>
</authenticate>
</pcoip-broker>

authenticate-resp message¶

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<authenticate-resp method="password">
   <result>
      <result-id>AUTH_SUCCESSFUL_AND_COMPLETE</result-id>
      <result-str>Authentication completed successfully</result-str>
   </result>
</authenticate-resp>
</pcoip-broker>

get-resource-list message¶

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Cookie: JSESSIONID=aabbccddeeff00112233445566778899<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<get-resource-list>
</get-resource-list>
</pcoip-broker>

get-resource-list-resp message¶

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<get-resource-list-resp>
   <result>
      <result-id>LIST_SUCCESSFUL</result-id>
      <result-str>The user is entitled to resources</result-str>
   </result>
   <resource>
      <resource-name>My Desktop</resource-name>
      <resource-id>abcdef0123456789</resource-id>
      <resource-type session-type="VDI">DESKTOP</resource-type>
      <resource-state>UNKNOWN</resource-state>
      <protocols>
         <protocol is-default="true">PCOIP</protocol>
      </protocols>
   </resource>
   <resource>
      <resource-name>My Session Desktop</resource-name>
      <resource-id>abcdef9876543210</resource-id>
      <resource-type session-type="RDS">DESKTOP</resource-type>
      <resource-state>UNKNOWN</resource-state>
      <protocols>
         <protocol is-default="true">PCOIP</protocol>
      </protocols>
   </resource>
</get-resource-list-resp>
</pcoip-broker>

allocate-resource message¶

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Cookie: JSESSIONID=aabbccddeeff00112233445566778899<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<allocate-resource>
   <resource-id>abcdef0123456789</resource-id>
   <protocol>PCOIP</protocol>
   <client-info>
      <time-zone-windows>Pacific Standard Time</time-zone-windows>
      <ip-address>192.168.0.57</ip-address>
      <mac-address>00:67:a8:2d:84:7e</mac-address>
   </client-info>
</allocate-resource>
</pcoip-broker>

allocate-resource-resp message¶

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<allocate-resource-resp>
   <result>
      <result-id>ALLOC_SUCCESSFUL</result-id>
      <result-str>Successfully allocated resource</result-str>
   </result>
   <target>
      <ip-address>192.168.1.56</ip-address>
      <hostname>mydesktop.teradici.com</hostname>
   </target>
   <resource-id>desktop-id</resource-id>
   <protocol>PCOIP</protocol>
</allocate-resource-resp>
</pcoip-broker>

bye message¶

This is an optional message. The PCoIP client may send this message to end the broker session.

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Cookie: JSESSIONID=aabbccddeeff00112233445566778899<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<bye>
   <reason>Connection complete</reason>
</bye>
</pcoip-broker>

bye-resp message¶

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<bye-resp>
</bye-resp>
</pcoip-broker>

Errors¶

If an error occurs at the application layer, then the broker is responsible for generating an <error-resp>.

The following example request is a malformed request. The <client-info> element is not closed.

POST /pcoip-broker/xml HTTP/1.1<CR><LF>
Host: <CR><LF>
User-Agent: xxxx<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
   <hello>
      <client-info>
   </hello>
</pcoip-broker>

In this case, the broker would create an <error-resp> message. The following is an example of an appropriate message.

HTTP/1.1 200 OK<CR><LF>
Date: Sun. 1 Jul 2012 16:40:00 GMT<CR><LF>
Set-Cookie: JSESSIONID=aabbccddeeff00112233445566778899; HttpOnly; Secure<CR><LF>
Client-Log-Id: 4208fb66-e22a-11d1-a7d7-00a0c982c00d<CR><LF>
Content-Type: application/xml charset=UTF-8<CR><LF>
Content-Length: xxxx<CR><LF>
<CR><LF>
<?xml version="1.0" encoding="UTF-8"?>
<pcoip-broker version="2.1">
<error-resp>
   <result>
      <result-id>ERR_INVALID_MSG_FORMAT</result-id>
      <result-str>Invalid XML message format</result-str>
   </result>

   <detected-by>BROKER</detected-by>

   <!-- Optional error details -->
   <err-detail>failed to close ‘client-info’ element </err-detail>


</error-resp>
</pcoip-broker>