View source for Security/Reviews/B2G/Browser API Privilged Apps

{{SecTracker
|Component=Browser API
}}
{{SecTrackerItem
|Sectrackerstatus=OK
|Simpyn=No
|SecTrackerFSA=no
}}
[[Category:Web APIs]]



===Background===
This API was reviewed early on in the B2G project. The purpose of this second review is to revisit this API, as much has changed since the initial security review last year. Also it has now been decided that this API will be available to privileged apps (which currently means Web Apps reviewed and signed by the Mozilla marketplace.) Development of review guidance is needed so that third-party apps requesting this permission can be thoroughly reviewed to ensure safe use of this API.

===Overview===
The Browser API is designed to support apps which load many other websites as part of their operation. It provides extended powers to Apps to control the loading and display of child web pages, and provides protection by ensuring child and parent are never same-origin. Apps use this by adding the 'mozbrowser' attribute on an iframe, which (assuming the app has the permission to use this attribute), does the following:
- Pages loaded inside a browser frame are given a top level browsing context (i.e. they are not aware they are framed, window.top==window etc)
- Content inside a browser frane is not framed for the purposes of an x-frame-options header check
- The parent which embedded this page can call functions and listen to certain events in order to control the child content. Some of these functions grant limited cross-origin access to the parent.


=== API Summary ===

* Provide support so that a Browser can be implemented as a Web App
* Makes the iframe appear like a top-level browser window to the embedded content
* Provide an API for parent page to manipulate and listen for changes of the embedded content's state.

Currently only privileged web apps can be granted the 'browser' required to embed this frame (that is, an app with a type:'privileged' and signed by an authorized store. 

Specification:
* https://wiki.mozilla.org/WebAPI/BrowserAPI
Bugs:
* https://bugzilla.mozilla.org/show_bug.cgi?id=693515
Pages:
* https://developer.mozilla.org/en-US/docs/DOM/Using_the_Browser_API
Source:
* http://mxr.mozilla.org/mozilla-central/source/dom/browser-element

===Architecture===
At its core, the browser API extends the frame and iframe element to include a mozbrowser attribute which specifies that this embedded frame is a Browser Frame. The Browser frame allows the parent frame to listen to certain events and perform functions which would otherwise not be available or prevented by browser same origin policy. For content embedded inside a browser frame it appears as if it is inside a top-level browser window.

A parent page, with the appropriate permission, can embed another page in a browser frame. In addition to normal frame functions and events, this allows the parent to:
* take a screenshot
* send mouse and touch events to the page
* listen for events when the child navigates, opens a window, opens a modal dialog 
* receive various other events relating to child state
* be guaranteed to be different origin to child content (even if scheme, host & port match)

Web content embedded inside an browser frame:
* Is in a top-level browsing context (e.g. script calling window.top respects <iframe mozbrowser> boundaries.)
* Not treated as framed for the purposes of x-frame-options headers

===Data Flow Diagram===





===Threat Model===
Threat vectors:

*Untrusted web content escaping the <iframe mozbrowser> element
** JavaScript references to items not inside the iframe impossible when using OOP
** Attacking local web apps through shared resources (are there any?)
**Causing the parent frame to navigate
** Obtaining the permissions of the parent frame, ie being able to act like a browser
***Impact is minimal is API is kept limited - not sure if this will be possible

*Normal Browser Security controls weakened or not present
** URL Bar behavior? (need to expose SSL information)

*Frame related issues
** Must handle frame-busting code correctly
** Modal dialogs in the browser frame must not block parent page

*Untrusted web page content not segregated sufficiently from Web Apps
** Shared resources between untrusted content (i.e. page loaded in the mozbrowser) and the installed apps. Cookies?
** Other Origin based resource access (local storage, Indexed DB)
** DoS attacks against the phone (mitigated by separate process, but what about spamming functions which result in IPDL messages back to the B2G process? Especially for messages that result in costly functions)
** Permissions (what prevents a page loaded at sms.gaiamobile.org from getting SMS permissions?)

*Untrusted page might gain access to create an <iframe mozbrowser>

* Compromised child process might escalate privs through browser API
** code review underway

===Authorization Model===
*Implicit: An app will need to granted the browser permission