Firefox Bug 784402, Pointer Lock must respect iframe sandbox flag

Recently I’ve worked on the Firefox Bug 784402 – Pointer Lock must respect iframe sandbox flag.

This is a quick overview of what had to be done on the bug.

Sandbox flags

First lets check what the sandbox attribute does:
A quote from the w3c spec

The sandbox attribute, when specified, enables a set of extra restrictions on any content hosted by the iframe. Its value must be an unordered set of unique space-separated tokens that are ASCII case-insensitive. The allowed values are allow-forms, allow-popups, allow-same-origin, allow-scripts, and allow-top-navigation. When the attribute is set, the content is treated as being from a unique origin, forms and scripts are disabled, links are prevented from targeting other browsing contexts, and plugins are secured. The allow-same-origin keyword allows the content to be treated as being from the same origin instead of forcing it into a unique origin, the allow-top-navigation keyword allows the content to navigate its top-level browsing context, and the allow-forms, allow-popups and allow-scripts keywords re-enable forms, popups, and scripts respectively.

With pointerlock landing on Firefox 15, it was decided that a new sandbox flag should be created to restrict the pointerlock usage on embedded scripts in a page, so for example: if you add an advertisement script on your page, you don’t want to give the permissions to the advertisement to lock the pointer to itself.
To manage that, the allow-pointer-lock sandbox was created.

An overview of how the sandbox flags work:
List of flags:

 * This flag prevents content from navigating browsing contexts other than  
 * the sandboxed browsing context itself (or browsing contexts further  
 * nested inside it), and the top-level browsing context.  
 const unsigned long SANDBOXED_NAVIGATION = 0x1;

 * This flag prevents content from navigating their top-level browsing  
 * context.  
 const unsigned long SANDBOXED_TOPLEVEL_NAVIGATION = 0x2;

 * This flag prevents content from instantiating plugins, whether using the  
 * embed element, the object element, the applet element, or through  
 * navigation of a nested browsing context, unless those plugins can be  
 * secured.  
 const unsigned long SANDBOXED_PLUGINS = 0x4;

 * This flag forces content into a unique origin, thus preventing it from  
 * accessing other content from the same origin.  
 * This flag also prevents script from reading from or writing to the  
 * document.cookie IDL attribute, and blocks access to localStorage.  
 const unsigned long SANDBOXED_ORIGIN = 0x8;

 * This flag blocks form submission.  
 const unsigned long SANDBOXED_FORMS = 0x10;

 * This flag blocks script execution.  
 const unsigned long SANDBOXED_SCRIPTS = 0x20;

 * This flag blocks features that trigger automatically, such as  
 * automatically playing a video or automatically focusing a form control.  
 const unsigned long SANDBOXED_AUTOMATIC_FEATURES = 0x40;

 * This flag blocks the document from acquiring pointerlock.  
 const unsigned long SANDBOXED_POINTER_LOCK = 0x80;  

Parsing the flags

So we have a 32 bit integer to store the sandbox flags.

Breaking down the integer we have 8 bytes
We can represent each byte in hexadecimal format:

So the number 0xFFFFFFFF has all the bits turned ON

Knowing that, we could use each bit of the integer to represent a flag.
We don’t care about the decimal value of that integer, since we are using it to store flags and not values.
So by saying 0x1, we are telling to turn the first bit of the first byte on, 0x2 turns the second bit of the first byte on
0x10 on the other hand tells to turn the first bit of the second byte on.
Remember that we are using hexadecimal notation.

So in the end, what’s happening is that each flag is turning a different bit on the integer

Later we’ll be able to check if that specific bit is ON or OFF and determine the status of the flag.

One thing to keep in mind is that if the iframe doesn’t have the sandbox attribute, then all the flags are turned OFF by default.


If the iframe has an empty sandbox attribute, then all the flags are ON by default

 <iframe sandbox=""></iframe>  

To turn the flags off, you can specify the feature you want to enable in the sandbox attribute:

 <iframe sandbox="allow-pointer-lock allow-same-origin"></iframe>  

In the snippet above both the allow-pointer-lock and allow-same-origin flag would be turned OFF, all the other flags would be ON

This is the code that parses the sandbox flags:

 * A helper function that parses a sandbox attribute (of an <iframe> or
 * a CSP directive) and converts it to the set of flags used internally.
 * @param aAttribute the value of the sandbox attribute
 * @return the set of flags
nsContentUtils::ParseSandboxAttributeToFlags(const nsAString & aSandboxAttrValue) {
  // If there’s a sandbox attribute at all (and there is if this is being  
  // called), start off by setting all the restriction flags.  
  uint32_t out = SANDBOXED_NAVIGATION |

  if (!aSandboxAttrValue.IsEmpty()) {
    // The separator optional flag is used because the HTML5 spec says any  
    // whitespace is ok as a separator, which is what this does.  
    HTMLSplitOnSpacesTokenizer tokenizer(aSandboxAttrValue, ‘‘,
      nsCharSeparatedTokenizerTemplate < nsContentUtils::IsHTMLWhitespace > ::SEPARATOR_OPTIONAL);

    while (tokenizer.hasMoreTokens()) {
      nsDependentSubstring token = tokenizer.nextToken();
      if (token.LowerCaseEqualsLiteral("allow-same-origin")) {
        out &= ~SANDBOXED_ORIGIN;
      } else if (token.LowerCaseEqualsLiteral("allow-forms")) {
        out &= ~SANDBOXED_FORMS;
      } else if (token.LowerCaseEqualsLiteral("allow-scripts")) {
        // allow-scripts removes both SANDBOXED_SCRIPTS and  
        out &= ~SANDBOXED_SCRIPTS;
      } else if (token.LowerCaseEqualsLiteral("allow-top-navigation")) {
      } else if (token.LowerCaseEqualsLiteral("allow-pointer-lock")) {

  return out;

First all the flags are turned ON.
Then it checks if the sandbox attribute has any values, if it does it splits them and compares against the possible flags.
Once it finds a match, it does a BIT NEGATION on the flag and a BIT AND with the integer that has all the other flags.
What happens is that the flag being parsed is turned OFF.

In the end the integer with the status of all the flags is returned.

Locking the pointer

Now lets take a look at the code that checks for the allow-pointer-lock flag when an element requests pointerlock

 nsDocument::ShouldLockPointer(Element* aElement)  
 // Check if pointer lock pref is enabled  
 if (!Preferences::GetBool("full-screen-api.pointer-lock.enabled")) {  
 NS_WARNING("ShouldLockPointer(): Pointer Lock pref not enabled");  
 return false;  

 if (aElement != GetFullScreenElement()) {  
 NS_WARNING("ShouldLockPointer(): Element not in fullscreen");  
 return false;  

 if (!aElement->IsInDoc()) {  
 NS_WARNING("ShouldLockPointer(): Element without Document");  
 return false;  

 if (mSandboxFlags & SANDBOXED_POINTER_LOCK) {  
 NS_WARNING("ShouldLockPointer(): Document is sandboxed and doesn’t allow pointer-lock");  
 return false;  

 // Check if the element is in a document with a docshell.  
 nsCOMPtr ownerDoc = aElement->OwnerDoc();  
 if (!ownerDoc) {  
 return false;  
 if (!nsCOMPtr(ownerDoc->GetContainer())) {  
 return false;  
 nsCOMPtr ownerWindow = ownerDoc->GetWindow();  
 if (!ownerWindow) {  
 return false;  
 nsCOMPtr ownerInnerWindow = ownerDoc->GetInnerWindow();  
 if (!ownerInnerWindow) {  
 return false;  
 if (ownerWindow->GetCurrentInnerWindow() != ownerInnerWindow) {  
 return false;  

 return true;  

The ShouldLockPointer method is called every time an element requests pointerlock, the method does some sanity checks and makes sure everything is correct.
To check for the allow-pointer-lock sandbox flag, a BIT AND with the mSandBoxFlags and the SANDBOXPOINTERLOCK const is performed, we’ve looked at the SANDBOXPOINTERLOCK flag before, it has the value of 0x80
So if pointerlock is allowed, the mSandboxFlags would have the SANDBOXPOINTERLOCK flag OFF and the BIT AND would be false.

A big thanks to Ian Melven.
Ian is the one who implemented the sandbox attribute on Firefox and gave me some guidance on the PointerLock sandbox attribute bug.

Bug 728893 - Allow mochitest iframe to go fullscreen

Bug 728893 was encountered while implementing PointerLock.

A Quick Overview on Mochitests

By default an iframe is not allowed to go fullscreen mode, and since all the mochitests are run inside and iframe, if one of the mochitest needed to go fullscreen it would not work (pointerlock for example)

There are two different ways to run mochitests. With runtests.py or mochitest-plain(ends up running runtests.py)

  1. python ./obj-dir/_tests/testing/mochitest/runtest.py –test-path=dom/tests/mochitest/pointerlock
  2. TEST_PATH=/dom/test/mochitest/pointerlock make -C obj-dir/ mochitest-plain

The first one calls explicit the runtests.py, that is the script that creates the http server
The second one will run mochitest-plain.
Now what is mochitest-plain?
First we need to look at the root’s Makefile
Line 129 is including testsuite-targets.mk, that’s where mochitest-plain is defined

127 ifdef ENABLE_TESTS
128 # Additional makefile targets to call automated test suites
129 include $(topsrcdir)/testing/testsuite-targets.mk
130 endif

Here is where mochitest-plain is defined, it calls $(RUN_MOCHITEST)

128 mochitest-plain:
130 $(CHECK

In the end runtests.py is ran with some default flags

65 rm -f ./[email protected] &&
66 $(PYTHON) _tests/testing/mochitest/runtests.py –autorun –close-when-done
67 –console-level=INFO –log-file=./[email protected] –file-level=INFO
68 –failure-file=$(call core

Running the tests with mochitest-plain will add some flags to the execution of runtest.py

[[email protected] mozilla-central-diogogmt]$ TESTPATH=dom/tests/mochitest/pointerlock/ make -C ff-dbg/ mochitest-plain
make: Entering directory `/home/diogogmt/mozilla-central-diogogmt/ff-dbg’
rm -f ./mochitest-plain.log && /usr/bin/python2.7 _tests/testing/mochitest/runtests.py –autorun **–close-when-done**–console-level=INFO –log-file=./mochitest-plain.log –file-level=INFO –failure-file=/home/diogogmt/mozilla-central-diogogmt/ff-dbg/
tests/testing/mochitest/makefailures.json –symbols-path=./dist/crashreporter-symbols –test-path=dom/tests/mochitest/pointerlock/

The flag –close-when-done is set by default. However sometimes you may want to leave the browser window open for debug purposes. I’m not sure if there is a way to tell mochitest-plain not run the runtests.py with the –close-when-done flag not set. What I usually do is run the tests calling directly runtest.py, since it runs withouth any flags, giving me more flexbility.

When not specifying a file, the mochitest will load all the files of the dir and run them inside the harness

For example:
The mochitest Makefile contains the list of the dirs of some tests

45 DIRS +=
46 dom-level0
47 dom-level1-core
48 dom-level2-core
49 dom-level2-html
50 ajax
51 bugs
52 chrome
53 general
54 whatwg
55 geolocation
56 localstorage
57 orientation
58 sessionstorage
59 storageevent
60 $(NULL

In the geolocation Makefile all the tests for that module are listed

41 relativesrcdir = dom/tests/mochitest/geolocation
43 include $(DEPTH)/config/autoconf.mk
45 include $(topsrcdir)/config/rules.mk
48 testallowCurrent.html
49 test
50 testcancelCurrent.html
51 test
52 testclearWatch.html
53 test
54 test
55 testmanyCurrentSerial.html
56 test
57 testmanyWatchSerial.html
58 test
59 testoptionalapiparams.html
60 test
61 testwindowClose.html
62 test
63 testworseAccuracyDoesNotBlockCallback.html
64 geolocation.html
65 geolocation
66 networkgeolocation.sjs
67 windowTest.html
68 $(NULL)
70 libs:: $(
71 $(INSTALL) $(foreach f,$^,"$f") $(DEPTH)/

From line 48 to 67 are listed all the test files
Line 41 is defined the path where the files are located
Line 71 is the path where the files will be copied after compiling firefox, for example:

Running single tests
When running the test as a stand alone, there is no need for an iframe, the test is loaded in the parent window, so the element is allowed to go fullscreen, different from when the tests are run inside the harness.

The Problem

When we first started writing mochitests for pointerlock we had to find a way to run the tests inside the harness while setting them to fullscreen.
The solution was to use the same approach as the fullscreen tests. To create a harness inside the harness, for example


The solution was simple, we just had to add the attribute mozallowfullscreen=true to the mochitest iframe.
However, there are three places where the iframe gets defined:

server.js is used for mochitest-plain
browser_harness.xul is used for mochitest-chrome and mochitest-browser-chrome
plain-loop remains a mystery :P

For server.js:

 IFRAME({scrolling: "no", id: "testframe", width: "500", height: "300", mozallowfullscreen: "true"})  

For browser_harness.xul

 <iframe id="testframe" scrolling="no" width="550" height="350"></iframe>  

You can find the complete patch here

Sanity tests

To make sure the mochitest framework works, before running all the tests a list of sanity tests is executed to test the framework itself.
You can see the list of the tests in the /testing/mochitest/tests/Makefile.in

43 relativesrcdir = testing/mochitest/tests
45 include $(DEPTH)/config/autoconf.mk
48 MochiKit-1.4.2
49 SimpleTest
50 browser
51 $(NULL)
53 include $(topsrcdir)/config/rules.mk
55 _TEST
56 testsanity.html
57 test
58 testsanityException2.html
59 test
60 testSpecialPowersExtension.html
61 test
62 fileSpecialPowersFrame1.html
63 $(NULL)
65 ifneq ($(OS
66 # Disabled on Android for permaorange, see bug 688052
68 testsanityEventUtils.html
69 test
70 endif
71 # Copy the sanity tests into a subdirectory, so the top level is all dirs
72 # in the test screen.
73 libs:: $(TESTFILES)
74 $(INSTALL) $(foreach f,$^,"$f") $(DEPTH)/tests/$(relativesrcdir)/Harnesssanity

One thing to notice is the folder the sanity tests are copied to: Harness_sanity

After Firefox is compiled, all the tests are copied to /obj-dir/_tests/testing/mochitest/tests
So to run the geolocation tests for example:

  • TEST_PATH=dom/tests/mochitest/geolocation

The Harness_sanity on the other hand:

  • TESTPATH=Harnesssanity

Since allowing the iframe to go fullscreen mode could break other tests we decided to add a check on SimpleTest.finish() to cancel fullscreen mode if the test forgets to cancel it

 + // Cancel element fullscreen mode due to Bug 728893  
 + if (document && document.mozFullScreenElement) {  
 + document.mozCancelFullScreen();  
 + }  

So now we needed a test to make sure SimpleTest.finish was actually cancelling fullscreen.
My first thought was to have two test files, testfullscreen1.html and testfullscreen2.html. On testfullscreen1.html the element would be set to fullscreen mode and without cancelling call SimpleTest.finish(), then on testfullscreen2.html would check the fullscreen status of the iframe, it should be false since SimpleTest.finish() supposed to cancel it.
However, there was an easier way to write the test, with just one file instead of two.



 + /** Test for Bug 728893  
 + Checks if SimpleTest.finish cancels fullscreen mode  
 + The assertion happens after calling SimpleTest.finish  
 + Running the test without the harness won’t work  
 + **/  
 + SpecialPowers.setBoolPref("full-screen-api.enabled", true);  
 + SpecialPowers.setBoolPref("full-screen-api.allow-trusted-requests-only",  
 + false);  
 + SimpleTest.waitForExplicitFinish();  
 + var div = document.getElementById("div");  
 + document.addEventListener("mozfullscreenchange", function (e) {  
 + if (document.mozFullScreenElement === div) {  
 + SimpleTest.finish();  
 + }  
 + else {  
 + is(false, document.mozFullScreen,  
 + "SimpleTest.finish should cancel fullscreen mode");  
 + }  
 + }, false);  
 + function start() {  
 + SimpleTest.waitForFocus(function() {  
 + div.mozRequestFullScreen();  
 + });  
 + }  


The assertion “is(false, document.mozFullScreen, “SimpleTest.finish should cancel fullscreen mode”);” is happening after SimpleTest.finish is called, the reason that it is possible to still make assertions after calling SimpleTest.finish is because the test itself is being run inside the mochitest harness


 678 if (parentRunner) {  
 679 /* We’re running in an iframe, and the parent has a TestRunner */  
 680 parentRunner.testFinished(SimpleTest._tests);  
 681 } else {  
 682 SimpleTest.showReport();  
 683 }  

Line 678 checks if the test is being run inside a harness, if true it goes to the next test, but it doesn’t terminates the current one.
Different from line 682 that call showReport, terminating the current test and displaying the results.

**Big thans to Clint(ctalbert) for all the help with this bug