Communication Channel

Communication Between the Extension and the Posting-App

Testing: Components of this have been implemented, but the specification is not frozen

The communication channel is established to facilitate trusted communications between the Javascript applications viewed on the page, and the extension of the browser.

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 injectable 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 accept 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);

Privly API
The result of a cryptographic operation requested by the Injectable Application. The message body will be determined by the cryptographic operation requested by the injectable application. For more information, see Extension API.

var secretMessage = "The random identifier sent by the posting application";
var messageType = "PrivlyAPI";
var messageBody = "This is dependent on the cryptographic operation requested";
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.

Three types of events will be monitored for in the extension.

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);