Status

Feature tracking bug

• bug postMessage

Has a design review been completed?

Smaug, sicking, and jst have commented on previous iterations of the patch, some in passing, more recently in detail, informing implementation of postMessage and the set of automated tests that accompanies the patch. There's also been discussion in WHATWG (ongoing) over this, although its being implemented by three separate browsers means that, for the most part, changes are going to be reasonably minimal from now on.

When do you anticipate the feature landing

This feature landed just before b3 freeze.

Overview

Window.postMessage is an API specified by HTML5 and WHATWG, originally implemented in Opera, for allowing a window/script to securely communicate with another window/script across origins (so for example, example.com could communicate with otherdomain.test), dependent upon the receiver actively handling the sent message. Its signature is:

void postMessage(in DOMString message);

When window A wishes to communicate with window B, it calls the postMessage method on B with the message it wishes to send:

B.postMessage("Hello from window A!");

Note that this requires the postMessage property of windows to be allAccess, in the same manner as window.blur(). This is admittedly dangerous, but the implementation of this is exactly one line added to modules/libpref/src/init/all.js, so there's little added risk from this. It should be noted that this is a method which takes an argument, while the existing allAccess properties of Window are either scalars or no-arg functions, so this broadens the attack surface a little. We do have precedent for such properties, however -- History.go() similarly takes an argument (albeit a number), and an XSS exploit of that could likely be pretty bad.

Once the method is called, the UA then creates a MessageEvent (a new event type) and dispatches it at the document for the target window, returning when the event has gone through the usual event dispatch process. A MessageEvent has four special properties: data, domain, uri, and source. data is the sent message, domain and uri represent the principal of the sending script's window, and source is the sending window. A receiver (who, it must be noted, must first be added as an event listener for the type "message" on the document or its window parent) can verify authenticity of a message using the domain and uri properties, which are unforgeable so long as an arbitrarily-constructed MessageEvent cannot be dispatched at the document by another origin (which it cannot by the same-origin requirement). source provides another verification mechanism and an avenue for a response.

This API was fairly stably specified by WHATWG for quite a while; recently, at least partly due to our implementing it, it has undergone further discussion of ways to make it more secure by default and to tweak the interface a little. However, as Opera, WebKit, and we all implement it, this will limit the changes considerably going forward. I've been talking to Hixie and others on #whatwg about it, and there's sensitivity to changes being made for this reason.

Use Cases

postMessage is useful in any case where one window wishes to communicate with another, untrusted window (or vice versa). Gadget-like functionality such as that provided by Google Gadgets could use this to allow widgets to be securely hosted on a separate domain, rather than requiring the client site to host them or provide a hole through which the widget content could be served. Facebook applications could be sandboxed into iframes yet under the hood use postMessage to access trusted functionality in the parent window containing Facebook privileged functions. Cross-domain communication has been attempted using various hacks in the past; one such attempt provides further reasons for making limited cross-domain communication possible.

Requirements

List functional and non-functional requirements for the feature here, with links back to any relevant product PRD. These requirements should be prioritized.

The ideal patch must be:

• secure; authentication mechanisms must not be forgeable, and messages must only be dispatchable across origins by the trusted code that implements postMessage
• match the HTML5 specification, when clearly specified
• have reasonable behavior in cases where behavior is not yet specified
• have sufficient testcases to demonstrate these behaviors

Schedule

The patch is functionally complete; once reviews have been completed it is ready to land immediately.

UI Design Documentation

N/A

Design Impact

Security and Privacy

• What security issues do you address in your project?

This feature addresses the relative insecurity of current mechanisms for communicating across domains, which rely upon extant holes in the same-origin model, in ways they were not designed to support. Current mechanisms are fragile and rely upon large holes in the same-origin restriction; the size of the hole this opens is small and well-defined.

• Is system or subsystem security compromised in any way if your project's configuration files / prefs are corrupt or missing?

The absence of the single preference in all.js safely prevents access to postMessage entirely.

• Include a thorough description of the security assumptions, capabilities and any potential risks (possible attack points) being introduced by your project.

The key concern that this functionality presents is that identifiers can be forged; this concern is addressed by testing as many different methods of use as possible, as well as by responding to feedback provided during implementation. Secondary concerns relate to the allAccess nature of postMessage; these most likely already exist with History.get, and furthermore they are more in scope for an XPConnect or caps modification than for a modification which merely uses functionality provided by XPConnect/caps.

Exported APIs

• Please provide a table of exported interfaces (APIs, ABIs, protocols, UI, etc.)

interface nsIDOMWindowInternal
+ void postMessage(in DOMString message);

+ interface nsIDOMMessageEvent : nsIDOMEvent {
+   attribute DOMString data, domain, uri;
+   attribute nsIDOMWindow source;
+   void initMessageEvent(/* usual args plus four */);
+   void initMessageEventNS(/* usual args plus four */);

Note that this may change somewhat due to recent WHATWG discussion, but I don't anticipate significant changes.

• Does it interoperate with a web service? How will it do so?

N/A

• Explain the significant names, syntax, and semantics.

See the overview section.

• Are the externally visible interfaces documented clearly enough for a non-Mozilla developer to use them successfully?

Yes, and the HTML5 specification describes the API fairly clearly (only at the edges and in interactions with as-yet-unspecified functionality is it less than adequate, but our tests define very specific behaviors in these cases). Again, note unfrozenness of spec...

• Does it change any existing interfaces?

The unfrozen interface nsIDOMWindowInternal grows a method, and the nsIDOMMessageEvent interface is added.

Web Compatibility

• Does the feature have any impact on Web compatibility?

WebKit nightlies implement postMessage, and Opera has an implementation available upon Document. I've submitted our tests to WHATWG for other implementers to use, as well.

Performance

• How will the project contribute (positively or negatively) to "perceived performance"?

postMessage is a performance win for cross-domain communication. Existing methods for communication are not synchronous and may involve polling or unnecessary and gratuitous event listeners, resulting in increased time and resource consumption.

• What are the performance goals of the project? How were they evaluated? What is the test or reference platform and baseline results?

The primary concerns during implementation were correctness and security; given the relative un-complexity of the implementation, it seems likely that performance will be primarily gated by XPConnect and event dispatch speed.

• Will it require large files/databases (for example, browsing history)?

No.

Reliability

• What failure modes or decision points are presented to the user?

This API has no user-visible UI unless a page chooses to display UI while handling a message.

• Can its files be corrupted by failures? Does it clean up any locks/files after crashes?

N/A

l10n and a11y

• are any strings being changed or added?

N/A

• are all UI elements available through accessibility technologies?

N/A

Installation, Upgrade/Downgrade/Sidegrade, and platform requirements

• Does it equally support all Tier-1 platforms?

Yes.

• Does is have a hardware requirement (or increase minimum requirements)?
• Does it require changes to the installer?
• Does it impact updates?

No.

• List the expected behavior of this feature/function when Firefox is upgraded to a newer minor release, downgraded by installation of an earlier revision, or re-installed (same version)

postMessage functionality would disappear in a downgrade, but otherwise no change.

configuration

• Can the end user configure settings, via a UI or about:config? Hidden prefs? Environment variables?

The sole preference to make postMessage allAccess is hidden from display by about:config.

• Are there build options for developers? [#ifdefs, ac_add_options, etc.]
• What ranges for the tunable are appropriate? How are they determined?

The API is not tunable.

• What are its on-going maintenance requirements (e.g. Web links, perishable data files)?

None; automated tests should ensure ongoing compliance with expected behavior.

Relationships to other projects - are there related projects in the community?

Nothing within the Mozilla community.

• Are you updating, copying or changing functional areas maintained by other groups? How are you coordinating and communicating with them? Do they "approve" of what you propose?

Smaug, sicking, and jst all looked at the implementation as it progressed and provided reviews before it landed.

Documentation

• Documentation for developer.mozilla.org?

http://developer.mozilla.org/en/docs/DOM:window.postMessage

Other

N/A

Discussion & Implications

Caveats / What We've Tried Before

N/A

References

Cross-document messaging, HTML5

Notes on things to worry about:

• add file: URL tests for postMessage
• add a second URI argument to postMessage
• consider what happens when a window redefines postMessage and what happens
• think about adding some way for whitelisting on the receiving end (e.g. the createMessageReceiver thing suggested on WHATWG), so you don't have to do an explicit check every time the event listener is called