Backplane Specification 1.2


June 23, 2011

Abstract

Backplane is a framework that facilitates message exchanges and event notifications between third-party JavaScript components within a web page.



Table of Contents

1.  Introduction
2.  Definitions
    2.1.  Requirements Language
3.  Overview
4.  Trust
5.  Access Levels
    5.1.  Regular Access
    5.2.  Privileged Access
6.  Padded Responses
7.  Buses
8.  Channels
9.  Backplane Messages
10.  Backplane Frames
11.  Message Retention
    11.1.  Sticky Messages
12.  Message Retrieval Conventions
13.  Backplane Server API
    13.1.  Get A New Channel Name
    13.2.  Get All Messages In A Bus
    13.3.  Get Channel Messages
    13.4.  Post Messages To A Channel
14.  Backplane JavaScript API
    14.1.  Initialization
    14.2.  Subscription Management
    14.3.  Hints
    14.4.  Usage Example
15.  Security Considerations
    15.1.  Channel Name Sensitivity
    15.2.  Message Payloads
16.  Normative References
§  Authors’ Addresses




 TOC 

1.  Introduction

Web pages have evolved from being loaded from a single resource to being able to reference third-party, external components that get loaded, run and rendered by the web browser within the same web page.

These components can be active and continue to run after the web page completed loading and are generally decoupled — not under the control of a single entity.

Interactions between the end user, the web page, and its features provided through such components can greatly benefit when all parties involved can exchange information with each other, and can do it in a standardized way.

The Backplane framework facilitates such interactions by providing an open standard API that is secure in the context of the assumed trust relationships between the parties involved. Messages are delivered reliably and in order. The framework may be used in different scenarios which build on top of the transport-level semantics described in this document.



 TOC 

2.  Definitions

Web Page
Document obtained from a web resource and loaded by the end user’s web browser.
Widget
Third-party JavaScript component referenced from the Web Page that is loaded and run in the end user’s browser.
Backplane Client
Entity that uses the Backplane framework to exchange information.
Backplane Message
A JSON object representing the unit of communication between Backplane Clients.
Backplane JavaScript API
JavaScript API used by Widgets to initialize and subscribe to Backplane Messages.
Backplane JavaScript Library
Backplane Client that also implements the Backplane JavaScript API.
Backplane Server API
Server API through which Backplane Clients send and retrieve Backplane Messages.
Backplane Server
Backplane Server API implementation.
Backplane Frame
A Backplane Message and metadata assigned to it by the Backplane Server.
Bus
Logical grouping of Backplane Clients that need to interact with each other, typically belonging to one organization.
Channel
Subset of Backplane Messages that belong to a Bus and are addressed to the Backplane Clients interacting with the end user through a single session and Web Page.
Channel Name
The part of the Channel identifier that is unique within a Bus.



 TOC 

2.1.  Requirements Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119].



 TOC 

3.  Overview

An operational Backplane framework consists of the following components:

  • A Backplane Server
  • A Backplane JavaScript Library
  • Widgets
  • Widgets’ server-side counterparts that act as Backplane Clients.

A Backplane Server is an independent orchestrator of the message interchange between Backplane Clients and may serve multiple independent Buses.

A Backplane framework instance needs to be configured prior to use: all Backplane Clients and the Server have to share the same Bus. Backplane Clients operating at the Privileged Access Level (Privileged Access) need a password to authenticate themselves to the Server. It is outside the scope of this document how such configuration is performed.



 TOC 

4.  Trust

The Backplane framework is intended to be used and operate under the following trust relationships. Any number of security issues can arise if any of these assumptions do not hold.

The end user trusts the Web Page owner (and indirectly all Widget owners) that the Web Page will not attack or exploit their web browser.

The Web Page owner (and indirectly the end user) trusts all Widget owners that the Widgets will not abuse the Backplane framework by trying to impersonate other Widgets’ behavior in order to obtain and access information that is not directed to them, such as end user account information addressed to other Widgets.

The Web Page owner (and indirectly the end user), and Widget owners trust the Backplane Server API and Backplane JavaScript API implementations that they will comply with this specification.

The Web Page owner (and indirectly the end user) trusts all content on the Web Page to not attack the widgets or the Backplane framework. This must explicitly include all JavaScript loaded for any purpose, including JavaScript that is not part of any of the Widgets on the Web Page.

Backplane Clients trust the Bus owner and the authenticity of Backplane Messages received through a Bus, i.e all Backplane Clients that were granted permission to post on the Bus by its owner.



 TOC 

5.  Access Levels

Considering the significantly different security enforcement capabilities of applications running in a web browser versus the ones running on a web server, two access levels are defined for Backplane Clients: Regular and Privileged.



 TOC 

5.1.  Regular Access

Regular access level is given to Backplane Clients running in the web browser (Widgets and the Backplane JavaScript Library).

Regular access level is exercised without presenting any authorization credentials aside from the Channel identifier. Bus owners and Backplane Servers acting on their behalf MUST NOT give authorization credentials for Privileged access level to Backplane Clients running in the web browser.

Backplane Clients having Regular access level can retrieve Backplane Frames sent to Channels for which they know the Channel identifier.



 TOC 

5.2.  Privileged Access

Privileged access level is given to Backplane Clients that are not running in a web browser, typically the Widgets’ server-side components.

Privileged access level is exercised by presenting authorization credentials obtained from the Bus owner for such operations. The authorization credentials MUST be sent using HTTP Basic Authentication with the corresponding Backplane Server API requests. Backplane Servers MUST validate the authorization credentials for all Backplane Server API operations that require Privileged access level, summarized below. See Backplane Server API (Backplane Server API). The provisioning of Privileged access level credentials is outside of the scope of this specification.

Backplane Clients having Privileged access level can perform the following operations on a Bus for which they have obtained authorization credentials from the Bus owner:

  • retrieve Backplane Messages that were sent to a Channel for which they know the Channel identifier
  • retrieve all Backplane Messages sent to the Bus
  • post Backplane Messages to a Channel for which they know the Channel identifier



 TOC 

6.  Padded Responses

For API requests made by the Javascript Library, the response is formatted specially.

The response body begins with the value of the callback parameter from the request. That value is followed by a “(” (opening parenthesis), then the JSON-encoded result value, then a “)” (closing parenthesis).

Example HTTP padded response body for a Get A New Channel Name (Get A New Channel Name) API call with the value “callback” for the callback parameter.

callback("8ec92f459fa70b0da1a40e8fe70a0bc8")


 TOC 

7.  Buses

A Bus is a logical grouping of Backplane Clients that need to interact with each other, typically belonging to one organization. Buses allow a Backplane Server to service multiple customers. Bus names can consist of short strings referencing the Bus owner’s name (e.g. “customer.com”, “organization.org”).

Bus identifiers are URLs consisting of the Backplane Server’s Bus endpoint and the Bus name. They are used by Backplane Clients for message retrieval and act as a namespace for the Backplane Messages exchanged by the group. Backplane Clients must know the identifiers for the Buses through which they wish to exchange Backplane Messages.

It is assumed that a relationship of trust exists between all clients granted permission to post messages to a specific Bus. See Trust (Trust).

Example of a Bus identifier:

http://backplane.example.com/v1.2/bus/customer.com

In this example http://backplane.example.com/v1.2/bus/ is the Backplane Server Bus endpoint and customer.com is the Bus name.



 TOC 

8.  Channels

A Channel is a subset of Backplane Messages that belong to a Bus and are addressed to the Backplane Clients interacting with the end user through a single session and Web Page. A Channel is similar to a session identifier for the user but is shared by multiple Backplane Clients.

Channel identifiers are URLs consisting of the Backplane Server’s Channel endpoint and the Channel Name and are used by Backplane Clients for message retrieval. All Backplane Clients that know a given Channel identifier can receive Backplane Messages posted to that Channel.

Channels are:

  • allocated within Buses
  • referenced by unique, unguessable identifiers (URLs)
  • created implicitly once a Backplane Message gets posted to a channel that doesn’t yet exist
  • non-persistent and expire after being inactive (no messages posted) for specific amount of time (e.g. 30 minutes)
  • sensitive (i.e. content that cannot be trusted to keep the Channel identifier secret MUST NOT be loaded)

Channel Names MUST only contain characters from the base64url (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.) [RFC4648.section5] character set.

Example of a Channel identifier:

http://backplane.example.com/v1.2/bus/customer.com/channel/8ec92f459fa70b0da1a40e8fe70a0bc8

In this example http://backplane.example.com/v1.2/bus/customer.com/channel/ is the Backplane Server Channel endpoint and 8ec92f459fa70b0da1a40e8fe70a0bc8 is the Channel Name.



 TOC 

9.  Backplane Messages

A Backplane message is a JSON object with the following fields:

source
the source of the message, MUST be a URL (e.g. “http://client.com/”)
type
message type, string
sticky
sticky flag, boolean. See Sticky Messages (Sticky Messages)
payload
arbitrary object carrying data specific to the particular message type

A Backplane message MAY be wrapped in a Magic Envelope (Panzer, J. and B. Laurie, “Magic Signatures,” February 2010.) [draft‑panzer‑magicsig‑00]. Backplane Clients MUST be able to process (unwrap) such messages (note that unwrapping a magic envelope is not the same as signature verification).



 TOC 

10.  Backplane Frames

A Backplane frame is a JSON object with the following fields:

message
the Backplane Message
channel_name
the Channel Name the message was posted to (can be used to construct Channel identifier of the message)
id
an arbitrary string identifier assigned by the server to the message for the purpose of later referencing

For the purpose of managing and referencing Backplane Messages, a Backplane Server wraps them with the meta information described above into Backplane Frames.



 TOC 

11.  Message Retention

Backplane Servers MUST maintain a window of most recent messages for each of the existing Channels. The window size MUST be at least 1 minute. It is RECOMMENDED that Backplane Servers maintain a window of at least 5 minutes.

It is RECOMMENDED that it is an operational priority for Backplane Servers to make messages available for retrieval as soon as possible after they are posted.

Backplane Clients that require reliable message delivery MUST poll their Backplane Servers with an interval of 30 seconds or less in order to avoid omissions.



 TOC 

11.1.  Sticky Messages

Some Backplane application scenarios may require longer lived Backplane Messages, such as for keeping a shared state about a end user’s logged-in identity or profile data.

Support for such scenarios is accomplished by flagging messages as “sticky” when they are posted (see Post Messages To A Channel (Post Messages To A Channel)). Backplane Servers MUST retain sticky messages for at least X minutes. It is RECOMMENDED that Backplane Servers retain sticky messages for Y minutes.

Backplane Clients can request retrieval of Backplane Frames that only encapsulate sticky messages by using the “sticky” request parameter. See Message Retrieval Conventions (Message Retrieval Conventions) below.

Application scenario protocols MUST specify the criteria for posting sticky messages, if any, such as defining certain message types or operations as sticky.

Application scenario protocols SHOULD define sticky messages in such a way as to minimize the number of sticky messages that may be retained by the Backplane Server at any one time for a channel, in order to reduce complexity of retrieval and processing by the Backplane Clients that rely on them.



 TOC 

12.  Message Retrieval Conventions

All Backplane Server API methods dealing with Backplane Message retrieval observe the principles outlined below.

A retrieval request may contain an optional ‘since’ parameter, referring to a Backplane Frame previously seen by the caller. If the ‘since’ parameter is…

…omitted, the whole window worth of Backplane Frames is returned.

…present and refers to a Backplane Frame…

…currently residing in the window, the Backplane Server returns all Backplane Frames that are more recent than the referenced one.

…which is no longer in the window, the whole window worth of Backplane Frames is returned.

A retrieval request may contain an optional ‘sticky’ parameter. The only value permitted for the ‘sticky’ parameter is “true”. If the ‘sticky’ parameter is…

…present with the value “true”: only the sticky Backplane Frames are returned.

…omitted: the current window with all non-sticky and sticky Backplane Frames is returned.

If both the ‘since’ and ‘sticky’ parameters are included in a request, their effect is combined. The Backplane Server MUST return all sticky Backplane Frames that are more recent than the one referenced by the ‘since’ parameter.



 TOC 

13.  Backplane Server API

A Backplane Server provides the following API.



 TOC 

13.1.  Get A New Channel Name

Endpoint
/v1.2/bus/<BUS NAME>/channel/new
HTTP Method
GET
Security
optional HTTPS, Regular Access Level (Regular Access)
Parameters
callback: the callback name (Padded Responses) to pad the response with.
Returns
a JSON string (a sequence of zero or more Unicode characters, wrapped in double quotes) containing a new, securely-generated Channel Name in a HTTP padded response (Padded Responses) body

This call exists to help the JavaScript Library provision new Channel Names. RFC 4086 (Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” June 2005.) [RFC4086] discusses the requirements and pitfalls of generating unguessable values in great detail. None of the mechanisms it suggests are available in JavaScript, so a server-side component must be available to help generate unguessable values.

The result value of this call is a Channel Name. The Channel Name MUST be at least 32 characters indepedently chosen with uniform distribution from the set 0123456789abcdef. The Channel Name MUST NOT be guessable given knowledge of the algorithms in use or any details of the request being made. The result MUST be padded as specified in the padded response (Padded Responses) section.

As operational notes, this API call SHOULD NOT be implemented in a way that makes it capable of blocking and use of one of the mechanisms in section 7 of RFC 4086 (Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” June 2005.) [RFC4086] is RECOMMENDED.

Example HTTP padded response body with Channel Name:

callback("8ec92f459fa70b0da1a40e8fe70a0bc8")


 TOC 

13.2.  Get All Messages In A Bus

Endpoint
/v1.2/bus/<BUS_NAME>
HTTP Method
GET
Security
HTTPS with Privileged Access Level (Privileged Access)
Parameters
since (optional): Backplane Message identifier (see Message Retrieval Conventions (Message Retrieval Conventions) above)

sticky (optional): true (see Message Retrieval Conventions (Message Retrieval Conventions) above)
Returns
a JSON object consisting of a list of Backplane Frames

This method is used by Backplane Clients to receive all messages distributed on the specific Bus <BUS_NAME>.



 TOC 

13.3.  Get Channel Messages

Endpoint
/v1.2/bus/<BUS_NAME>/channel/<CHANNEL_NAME>
HTTP Method
GET
Security
Regular Access Level (Regular Access)
Parameters
callback (required): the callback name (Padded Responses) to pad the response with.

since (optional): Backplane Message identifier (see Message Retrieval Conventions (Message Retrieval Conventions) above)

sticky (optional): true (see Message Retrieval Conventions (Message Retrieval Conventions) above)
Returns
a JSON object consisting of a list of Backplane Frames.

This method is used by Widgets to receive Backplane Frames corresponding to Backplane Messages that were posted to a specific Channel. The result MUST be padded as specified in the padded response (Padded Responses) section.



 TOC 

13.4.  Post Messages To A Channel

Endpoint
/v1.2/bus/<BUS_NAME>/channel/<CHANNEL_NAME>
HTTP Method
POST
Security
HTTPS, Privileged Access Level (Privileged Access)
HTTP Request Body
a JSON object consisting of a list of Backplane Messages to post to the channel

This method injects one or more Backplane Messages to the Channel. If Channel <CHANNEL_NAME> doesn’t exist, it is created.



 TOC 

14.  Backplane JavaScript API

A Backplane JavaScript Library runs in an end user’s browser and mediates communication between Backplane-enabled Widgets on the page and the Backplane Server.

Only one instance of the Backplane JavaScript Library on a given page is possible. The library has to be the first to load on the page to make it possible for other scripts to use its subscription functionality.

The Backplane JavaScript Library provides the following API (all methods are static):

/**
 * Initializes the backplane library
 *
 * @param {Object} Params - hash with configuration parameters.
 *   Possible hash keys:
 *     serverBaseURL (required) - Base URL of Backplane Server
 *     busName (required) - Customer's backplane bus name
 */
Backplane.init(Params);

/**
 * Subscribes to messages from Backplane server
 *
 * @param {Function} Callback - Callback function which accepts backplane messages.
 * @returns Subscription ID which can be used later for unsubscribing.
 */
Backplane.subscribe(Callback);

/**
 * Removes specified subscription
 *
 * @param {Integer} Subscription ID
 */
Backplane.unsubscribe(SubscriptionID);

/**
 * Returns channel ID (like http://backplane.customer.com/v1.2/bus/customer.com/channel/8ec92f459fa70b0da1a40e8fe70a0bc8)
 *
 * @returns Backplane channel ID
 */
Backplane.getChannelID();

/**
 * Notifies backplane library about the fact that subscribers are going
 * to receive backplane messages within specified time interval.
 *
 * @param {Integer} TimeInterval - Time interval in seconds
 * @param {Array} MessageTypes (optional) - a list of expected message types
 */
Backplane.expectMessagesWithin(TimeInterval, MessageTypes);


 TOC 

14.1.  Initialization

Backplane is initialized using the Backplane.init method.

During initialization the library generates a random Channel Name unless information about one for the specified bus name already exists in the backplane-channel cookie. Since client-side generation of the Channel Name is non-secure, the library performs a request to obtain a Channel Name from the Backplane Server.

After initialization the library stores the current Channel Name in the backplane-channel cookie set against the complete domain name of currently opened page. The cookie is set for 5 years in advance and keeps information about association of Bus names to Channel Names (to support possibility to use the library with several different Bus names on the same domain). The information about the association is stored in a serialized form.

Here is an example of cookie that stores association of Bus names example.com and example.org to the corresponding Channel Names 123 and 456:

backplane-channel=example.com:123|example.org:456

After the channel ID has been determined, the library performs a first reading of messages from a channel, discards all of them (remembering only the identifier of the very last one) and starts polling the Backplane Server for new messages since the latest Backplane Message. This way the library is guaranteed to push to subscribers only those Backplane Messages which arrived after the library had been fully initialized.



 TOC 

14.2.  Subscription Management

The library provides a method for Widgets to set up notification callbacks: Backplane.subscribe. The method returns a subscription id which can be later used for unsubscribing using the Backplane.unsubscribe method.

After the initialization the library starts polling the Backplane Server for new events. All incoming events are delivered to the Widgets that have registered callbacks with the library.



 TOC 

14.3.  Hints

For performance reasons the Backplane JavaScript Library polls the Backplane Server with a low frequency (e.g once a minute). Since Backplane events usually are initiated on the client side (e.g. the user clicking a button), Widgets on the page are in a position to hint the library that a Backplane message may be soon delivered. Upon the receipt of such hint (via expectMessagesWithin method), the library temporarily increases the polling frequency (e.g. to once a second) and then gradually decreases it to the default low value one.

The expectMessagesWithin method can accept an optional list of expected message types.

If the library accepts any message from the passed message types list, it gradually returns to the lower polling frequency mode;

If messages with only one type are expected, the second argument may be specified as a string;

Each call of the method adds passed message types to the list of expected message types. In other words, if a user calls the method with a message type “type1″ and then performs one more call with a message type “type2″, the library will run in the fast polling mode until it received messages of all the types or until the libray reached the maximum allotted waiting time interval.



 TOC 

14.4.  Usage Example

Backplane.init({
    serverBaseURL: "http://backplane.customer.com/v1.2",
    busName: "customer.com"
});

var escSubscription = Backplane.subscribe(function(backplaneMessage) {
    alert(backplaneMessage.payload);
});

// We can ask the library to perform more frequent polling
// if a widget, for example, expects a message from Backplane pretty soon
// using the expectMessagesWithin method which accepts
// time interval of possible message arrival in seconds
Backplane.expectMessagesWithin(10);

// The method can accept an option list with expected message types.
// The library stops fast polling when it receives a message of
// either type.
Backplane.expectMessagesWithin(10, ["type1", "type2"]);

// Subsequent calls extend the list of expected message types.
// The library stops fast polling only after it has received
// a message of type1 or type2 AND a message of type3 or type4.
Backplane.expectMessagesWithin(10, ["type3", "type4"]);

Backplane.unsubscribe(escSubscription);

// If a widget needs Backplane channel ID it can get it using the
// getChannelID method
Backplane.getChannelID();


 TOC 

15.  Security Considerations

See Trust (Trust).



 TOC 

15.1.  Channel Name Sensitivity

The Channel Name acts as a session identifier shared among a group of trusted parties. Knowledge of a Channel Name offers Regular Access level to Backplane Server API.

It is therefore important that the Channel Name is not compromised, by either:

  • Trusting any third-party JavaScript source included in the Web Page without due verification, or
  • Disclosing Channel Names to untrusted parties.



 TOC 

15.2.  Message Payloads

Message payloads are sent to all Backplane Clients, including clients that run in the browser. Message payloads are therefore available to all JavaScript components loaded with the Web Page.

It is therefore important that Backplane Messages that contain sensitive data payloads that cannot be shared with all JavaScript components loaded with the Web Page are not posted to a Backplane Channel.



 TOC 

16. Normative References

[RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” BCP 14, RFC 2119, March 1997 (TXT, HTML, XML).
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol — HTTP/1.1,” RFC 2616, June 1999 (TXT, PS, PDF, HTML, XML).
[RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, “HTTP Authentication: Basic and Digest Access Authentication,” RFC 2617, June 1999 (TXT, HTML, XML).
[RFC4086] Eastlake, D., Schiller, J., and S. Crocker, “Randomness Requirements for Security,” BCP 106, RFC 4086, June 2005 (TXT).
[RFC4627] Crockford, D., “The application/json Media Type for JavaScript Object Notation (JSON),” RFC 4627, July 2006 (TXT).
[RFC4648.section5] Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” October 2006.
[draft-panzer-magicsig-00] Panzer, J. and B. Laurie, “Magic Signatures,” February 2010.


 TOC 

Authors’ Addresses

  Chris Saad
  Echo
Email:  chris@aboutecho.com
URI:  http://aboutecho.com
   
  Vlad Skvortsov
  Echo
Email:  vss@aboutecho.com
URI:  http://aboutecho.com
   
  Yuri Lukyanov
  Echo
Email:  snaky@aboutecho.com
URI:  http://aboutecho.com
   
  Alexander Zhuravlev
  Echo
Email:  zaa@aboutecho.com
URI:  http://aboutecho.com
   
  Ivan Glushkov
  Echo
Email:  gli@aboutecho.com
URI:  http://aboutecho.com
   
  Carl Howells
  Janrain
Email:  chowells@janrain.com
URI:  http://www.janrain.com/
   
  Johnny Bufu
  Janrain
Email:  jbufu@janrain.com
URI:  http://www.janrain.com/