Communication Channel

Communication Between the Extension and the Posting-App

Version History

Testing 0.1: This specification is used by both the [PlainPost][Posts] and ZeroBin Injectable Applications.

Description

A posting application is one which generates a new [Privly-type][URL-Specification] link for addition to the host page. For example, when you right-click a form element in a webmail client and click "Encrypt and Post," the resulting application that adds the URL to the form element is a posting application.

This specification provides a method for securely messaging these posting applications configuration parameters, and starting values, as well as provides a way for the application to give the resulting URL to the extension for automatic posting to the host page.

This communication channel works for both locally served applications (served from the extension) and remotely served posting applications. It is the responsibility of the extension to determine which requests it will process from the posting application. More advanced posting applications making use of the compiled library functionality may need to be served directly from the extensions in order to benefit from full API library access.

Initialization

Different browsers have different methods of securely communicating with web applications, but we need a consistent way to securely manage the communication. A common problem is platform differences in the way messages are handled, which prevents common code for verifying sender identity. To abstract away the differences, we send a message from the posting application to the extension using an event. The event is fired with a secret identifier, which can only be captured by the extension. All subsequent messages will then contain the secret identifier, and the application will trust the data.

The posting application is responsible for generating a random token and sending it to extensions with an event. We recommend you use the following code:

var secret = Math.random().toString(36).substring(2) + 
             Math.random().toString(36).substring(2) +  
             Math.random().toString(36).substring(2);
var messageSecretElement = document.createElement("privlyEventSender");  
messageSecretElement.setAttribute("privlyMessageSecret", secret);  
document.documentElement.appendChild(messageSecretElement);  
var evt = document.createEvent("privlyEvents");  
evt.initEvent("PrivlyMessageSecretEvent", true, false);  
messageSecretElement.dispatchEvent(evt);

Note that this code will only be as strong as the local implementation of Math.random(). The random secret will be 48 characters long as shown above.

Messages to the Injectable Application

It is the responsibility of the extension to decide whether the injectable application should be sent any messages. All messages will be prefaced by the secret as initialized above.

An example on how to message the application is as follows:

var secretMessage = "The random identifier sent by the posting application";
var messageType = "The name of the message being sent to the posting application";
var messageBody = "What the extension wants to tell the application";
var injectableApplicationWindow = GetAReferenceToTheApplicationWindowHere;
injectableApplicationWindow.postMessage(secretMessage + messageType + messageBody);

Note that there are no characters separating the secretMessage from the messageType and the messageBody. It is the responsibility of the injectable application to parse the message.

The messages all injectable applications should send are:

Initial Content
The content the extension wants to seed the application with.

var secretMessage = "The random identifier sent by the posting application";
var messageType = "InitialContent";
var messageBody = "Usually the current value of a form element in a host page";
var injectableApplicationWindow = GetAReferenceToTheApplicationWindowHere;
injectableApplicationWindow.postMessage(secretMessage + messageType + messageBody);

Submit
A command to generate a URL with the current content of the application. Initial content must be sent to the application before the extension requests a submit.

var secretMessage = "The random identifier sent by the posting application";
var messageType = "Submit";
var messageBody = "None Required";
var injectableApplicationWindow = GetAReferenceToTheApplicationWindowHere;
injectableApplicationWindow.postMessage(secretMessage + messageType + messageBody);

Messages to the Extension

All messages from the Injectable Application to the extension are sent by firing DOM events on the page. The only current example of a message from the injectable application to the extension is the communication channel initialization shown above. It is the responsibility of the extension to define content scripts that monitor for the events and securely message them to the extension's context.

Three types of events are currently supported by the Chrome and Firefox extensions.

1. Secret Message Event: This event initializes the communication channel. For more information, read "Initialization" above.
2. URL event: This event signals the end of the posting process, and contains a newly generated URL. For more information, read about Posting Applications
3. API request: This event sends an encryption API request to the extension's Javascript code. For more information, read about Extension API

It is the responsibility of the extension to decide whether the sender's event should be processed. A generic DOM event used for sending messages is shown below:

var messageSecretElement = document.createElement("uniqueElementName");//only if it doesn't exist  
messageSecretElement.setAttribute("PrivlyAPI", "cryptographicFunctionCall");  
document.documentElement.appendChild(messageSecretElement);  
var evt = document.createEvent("privlyEvents");  
evt.initEvent("PrivlyAPI", true, false);  
messageSecretElement.dispatchEvent(evt);

Future Versions

Future versions will use JSON serialization/deserialization instead of the current method of prefixing the message string with an identifier.