-
Notifications
You must be signed in to change notification settings - Fork 73
Web Routing Protocol
Web Routing Protocol
This document specifies the web routing protocol design. The goal of this layer is to enable devices to interact with a centralized web router (cluster) that routes the messages to/from various services on the other side. From the service perspective, this layer provides a centralized mechanism to directly interact with millions of authorized devices in the field in a scalable manor.
Higher level protocols (GET/SET or event payloads) may be built on this layer, but are outside the scope of this specification.
. Scope of this document . .
~50M . .
Devices . .
. __--__ +---------+
+-----+ . ( ) | |
| STB |<----------( )--------->+ | +------------+ +-----+
+-----+ . ( ) | Web +<---->| REST Proxy |<--->| XPC |
. . ( Untrusted ) | Router | +------------+ +-----+
. . ( ) | Cluster | ^
. . ( Network ) | | |
+-----+ . ( ) | | +---------------+ |
| XB6 |<----------( )--------->+ +----->| Notification | |
+--+--+ . ( ) | | | Proxy Service |-----/ (example)
| . --__-- +---------+ +---------------+
| . .
| . . . . . . . . . . . . . .
|
| +-----+
+-->| STB |
| +-----+
|
| +------------+
+-->| Thermostat |
| +------------+
|
| +------------------+
\-->| other IoT device |
+------------------+
If the system implementing this protocol layer is compromised, then the potential attacker(s) could gain control of many/all devices downstream. This is highly undesirable and all measures SHALL be taken to prevent this possibility.
The entire time a device is present on our network, we want to be able to communicate with it. As such, it is important to be able to work efficiently across networks, IP version (4 or 6) or limitations of small devices.
Given an estimated 1B transactions a day, the design be as efficient as possible to reduce the need to scale horizontally more then needed.
The devices (set top boxes, gateways, etc) will originate the connection to the web router over secure websockets (WSS). The web router does not establish any connection directly with any other components in the system with the possible exceptions:
- DNS
- Authorization Policy Service (Billing or similar)
Servers wishing to communicate with devices shall also establish (and maintain) connections to the web router.
The web router SHALL NOT permit direct device to device (so mac:{mac address} or serial:{serial number} names for example). Additionally, it is encouraged to direct server to server messages through channels outside the web router to reduce the possible load on the server.
Messages that are not able to be routed SHALL be dropped.
If "something bad" happens and nodes of the web router fail, messages WILL be lost. In this case clients and servers that discover they are disconnected are responsible for re-establishing the connection.
Message types that are not understood SHALL be discarded.
Any additional parameters (to the ones listed) for known message types SHALL be passed without alteration.
| Name | Description |
|---|---|
| web router | the server cluster that implements the WRP protocol |
| WRP | web routing protocol |
| WS | Websockets |
| WSS | Secure Websockets |
Messages in the document are defined and shall be implemented using MsgPack.
WRP
WS
HTTP
TLS/SSL
TCP
IP
Physical
A UTF-8 case insensitive string of one of the following:
uuid:{the uuid}/{service}/{ignored}dns:{host name}/{service}/{ignored}mac:{mac address}/{service}/{ignored}serial:{serial number}/{service}/{ignored}
There can be a number of possible ways a device may become identified. The name of the device depends mainly on how it needs to be known. Set top boxes (X1 or legacy for example) will likely choose to follow the mac:{mac address}/{service} or serial:{serial number}/{service} convention. A service (such as the web router, XPC or an adapter) would likely choose dns:{host name}/{service}. Other devices that perform application layer discovery may choose uuid:{the uuid}.
The identifiers are not resolved or verified except for routing purposes.
Note that if the mac:{mac address} or serial:{serial number} formats are used, the name of the device must be a known value or the routing will not make it to the device as there is not other registration messages.
For device identification describing services, there is an additional {service} path that allows multiple services to reside on a single server or node and get routed correctly. Any data past the {service}/ is ignored by the web router.
The following HTTP headers describe the device name and group membership in the WSS establishment:
| Name | Description |
|---|---|
X-WebPA-Device-Name |
(Required) The device name to refer to the device by. SHOULD be serial-{serial number}
|
X-WebPA-Group-Membership |
(Optional) The comma separated list of groups to which the device is a member. |
This API uses HTTP redirection where appropriate. Clients should assume that any connection request may result in a redirection. Clients should follow the redirect as this is not an error.
Redirections are limited to 5 redirects.
{
Integer msg_type = 2
Integer status
}
| Name | Description |
|---|---|
| msg_type | The message type for the authorization status message. (SHALL be 2.) |
| status | The status of the device to which the message is sent. |
Status Codes:
* 200 - Authorized
* 401 - Unauthorized - The service is not authorized for this account.
* 402 - Payment Required - The associated account needs payment.
* 406 - Not Acceptable - The certificate is not accepted.
{
Integer msg_type = 3
String transaction_uuid
String source
String dest
Array.String headers
Array.Array spans
Boolean include_spans
Binary payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the request-response. (SHALL be 3.) |
| transaction_uuid | The transaction key for the request and response. The requester may have several outstanding transactions, but must ensure that each transaction is unique per destination. This SHOULD be a UUID, but the web router SHALL NOT validate this data. The web router SHALL treat this data as opaque. |
| source | The device_id name of the device originating the request or response. |
| dest | The device_id name of the target device of the request or response. |
| headers | (optional) The headers associated with the payload. |
| spans | (optional) An array of arrays of timing values as a list in the format: "name", "start time", "duration" |
| include_spans | (optional) If the timing values should be included in the response. |
| payload | The MsgPack bin format packed data. |
{
Integer msg_type = 4
String source
String dest
Array.String headers
Binary payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the challenge response. (SHALL be 4.) |
| source | The device_id name of the device originating the request or response. |
| dest | The device_id name of the target device of the request or response. |
| headers | (optional) The headers associated with the payload. |
| payload | The bin format packed data. |
{
Integer msg_type = ( 5 | 6 | 7 | 8 )
String transaction_uuid
String source
String dest
Array.String headers
Array.Array spans
Boolean include_spans
Integer status
String path
Map payload
}
| Name | Description |
|---|---|
| msg_type | The message type for the CRUD interface. (5 = Create, 6 = Retrieve, 7 = Update, 8 = Delete) |
| source | The originating point of the request or response. |
| dest | The destination point of the request or response. |
| headers | (optional) The headers associated with the payload. |
| spans | (optional) An array of arrays of timing values as a list in the format: "name", "start time", "duration" |
| include_spans | (optional) If the timing values should be included in the response. |
| status | (optional) The response status. Ignored during the request. |
| path | The path to which to apply the payload. |
| payload | (optional) The msgpacked format data. |
| Method | Request | Response |
|---|---|---|
| Create | Name/value pairs for the new object | Resulting object |
| Retrieve | Ignored | Requested object |
| Update | Name/value pair to update | Ignored |
| Delete | Ignored | Ignored |
The following messages have been deprecated and shall not be used.
- 0
- 1
The device establishes the secure websocket connection to the web router shortly after the device boots. During the secure websocket connection is established, the web router SHALL authorization checks the device before any user messages are routed to or from the device.
If the web router is satisfied with the authorization available for the device the web router SHALL send the message with the status of 200 set. It SHALL then proceed to route messages to and from the device. The routing continues until a device is no longer authorized. If the web router is not pleased with the certification or authorization provided by the device, it SHALL send the response message with the appropriate status set and MAY disconnect the session. If a device fails an authorization, the web router SHALL respond to the device with the authorization response message with the status of 401 set.
At any time, either party may disconnect the session for any reason.
The connection request MAY result in a HTTP redirect to the device, so the device MUST be prepared to support that request.
Once a session is established, websocket ping messages MUST be sent from the device to the web router periodically. The web router MUST respond with a websocket pong.
The device SHALL NOT listen for any connection initiated by the web router. All session initiation originates from the device.
Authorization is a key component in the protocol because it reduces the risk of unintended user(s) or use(s) of this message routing service. Authorization status can change at any time. (Accounts can be revoked, cancelled, bills not payed, customers added, etc.) The protocol provides a mechanism for the web router to indicate the authorization status of the device to the device.
A key value of the authorization challenge model design is that the authorization only happens at the establishment of a websocket session and "periodically" afterwards. This important because often network protocols get bogged down re-validating credentials for each request or event and cannot horizontally scale to accommodate very large device populations.
The authorization checks happen at the server's discretion and may take place at any time.
Authorization checks may result in a status message sent to the device, disconnection of the device, or both.
Device Web Router Server
------------------------------------------------------------------------------------------
| | |
Boot | |
| | |
|--------- Open WSS --------->| |
| | +----------------------+ |
| | | Validate credentials | |
| | +----------------------+ |
| | |
| | (optional and for example) |
| ....|...............................|....................
| . | | .
| . |--- Check Account Status ----->| .
| . | | +---------------+ .
| . | | | Authorization | .
| . | | | Policy | .
| . | | | Service | .
| . | | +---------------+ .
| . |<--- Device is authorized -----| .
| . | | .
| ....|...............................|....................
| | |
|<---- Session Established ---| |
| | |
|<----- Auth Status ----------| |
| | |
. . .
. . .
| | |
|------ Websocket Ping ------>| |
|<----- Websocket Pong -------| |
| | |
Device Web Router REST Server
------------------------------------------------------------------------------------------
| | |
| | |
| | |
| | |<-- Incoming
| | | Request
| | |
| |<---- Send Request to device --|
| | |
| | +--------------------+ |
| | | Look up device | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
|<---- Request from REST -----| |
| | |
|----- Response to REST ----->| |
| | |
| | +--------------------+ |
| | | Look up service | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
| |------ Response to REST ------>|
| | |
| | |--> Response
| | |
| | |
Device Web Router Listening Server
------------------------------------------------------------------------------------------
| | |
|---- Event ----------------->| |
| | |
| | +--------------------+ |
| | | Look up service | |
| | | based on unique_id | |
| | | of open sessions | |
| | +--------------------+ |
| | |
| |----- Webhook call to -------->|
| | listener(s) |
| | |
This document is based on the 0.12 release of the internal spec.