Reference Sheet for Principals in Mozilla Code

Note: This is the reference sheet version. The details and the big picture are covered in Understanding Web Security Checks in Firefox (Part 1).

Principals as a level of privilege

A security context is always using one of these four kinds of Principals:

  • ContentPrincipal: This principal is used for typical web pages and can be serialized to an origin URL, e.g., https://example.com/.

  • NullPrincipal: Some pages are never same-origin with anything else. E.g., <iframes sandbox> or documents loaded with a data: URI. The standard calls this an opaque origin.

  • SystemPrincipal: The SystemPrincipal is used for the browser's user interface, commonly referred to as "browser chrome". Pages like about:preferences use the SystemPrincipal.

  • ExpandedPrincipal: A browser extension is more privileged than normal web pages, but must also be able to assume the security context of a website. Hence, an ExpandedPrincipal is best understood as a list of principals to match the security needs for Content Scripts in Firefox Extensions. The security checks on the ExpandedPrincipal are then implemented as a loop through this allowlist of principals.

Principals to be considered during security checks

  • loadingPrincipal: The principal of the document where the result of the load will be used.

  • triggeringPrincipal: The security context that actually triggered the URL to load. In most cases the loadingPrincipal and the triggeringPrincipal are identical. But imagine a cross-origin CSS resource loading a background image. Here, the triggeringPrincipal is principal for the CSS file.

As an aside: There's also a StoragePrincipal: To adjust anti-tracking settings in Firefox, we can change the Principal that a document is using for storage (and related technologies) on the fly. This is achieved with a StoragePrincipal.


If you find a mistake in this article, you can submit a pull request on GitHub.

Other posts

  1. Prompt Injections and a demo (Wed 18 September 2024)
  2. The Mozilla Monument in San Francisco (Fri 05 July 2024)
  3. What is mixed content? (Sat 15 June 2024)
  4. How I got a new domain name (Sat 15 June 2024)
  5. How Firefox gives special permissions to some domains (Fri 02 February 2024)
  6. Examine Firefox Inter-Process Communication using JavaScript in 2023 (Mon 17 April 2023)
  7. Origins, Sites and other Terminologies (Sat 14 January 2023)
  8. Finding and Fixing DOM-based XSS with Static Analysis (Mon 02 January 2023)
  9. DOM Clobbering (Mon 12 December 2022)
  10. Neue Methoden für Cross-Origin Isolation: Resource, Opener & Embedding Policies mit COOP, COEP, CORP und CORB (Thu 10 November 2022)
  11. Reference Sheet for Principals in Mozilla Code (Mon 03 August 2020)
  12. Hardening Firefox against Injection Attacks – The Technical Details (Tue 07 July 2020)
  13. Understanding Web Security Checks in Firefox (Part 1) (Wed 10 June 2020)
  14. Help Test Firefox's built-in HTML Sanitizer to protect against UXSS bugs (Fri 06 December 2019)
  15. Remote Code Execution in Firefox beyond memory corruptions (Sun 29 September 2019)
  16. XSS in The Digital #ClimateStrike Widget (Mon 23 September 2019)
  17. Chrome switching the XSSAuditor to filter mode re-enables old attack (Fri 10 May 2019)
  18. Challenge Write-up: Subresource Integrity in Service Workers (Sat 25 March 2017)
  19. Finding the SqueezeBox Radio Default SSH Password (Fri 02 September 2016)
  20. New CSP directive to make Subresource Integrity mandatory (`require-sri-for`) (Thu 02 June 2016)
  21. Firefox OS apps and beyond (Tue 12 April 2016)
  22. Teacher's Pinboard Write-up (Wed 02 December 2015)
  23. A CDN that can not XSS you: Using Subresource Integrity (Sun 19 July 2015)
  24. The Twitter Gazebo (Sat 18 July 2015)
  25. German Firefox 1.0 ad (OCR) (Sun 09 November 2014)
  26. My thoughts on Tor appliances (Tue 14 October 2014)
  27. Subresource Integrity (Sun 05 October 2014)
  28. Revoke App Permissions on Firefox OS (Sun 24 August 2014)
  29. (Self) XSS at Mozilla's internal Phonebook (Fri 23 May 2014)
  30. Tales of Python's Encoding (Mon 17 March 2014)
  31. On the X-Frame-Options Security Header (Thu 12 December 2013)
  32. html2dom (Tue 24 September 2013)
  33. Security Review: HTML sanitizer in Thunderbird (Mon 22 July 2013)
  34. Week 29 2013 (Sun 21 July 2013)
  35. The First Post (Tue 16 July 2013)
π