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.

Other posts

  1. Reference Sheet for Principals in Mozilla Code
  2. Hardening Firefox against Injection Attacks – The Technical Details
  3. Understanding Web Security Checks in Firefox (Part 1)
  4. Help Test Firefox's built-in HTML Sanitizer to protect against UXSS bugs
  5. Remote Code Execution in Firefox beyond memory corruptions
  6. XSS in The Digital #ClimateStrike Widget
  7. Chrome switching the XSSAuditor to filter mode re-enables old attack
  8. Challenge Write-up: Subresource Integrity in Service Workers
  9. Finding the SqueezeBox Radio Default SSH Passwort
  10. New CSP directive to make Subresource Integrity mandatory (`require-sri-for`)
  11. Firefox OS apps and beyond
  12. Teacher's Pinboard Write-up
  13. A CDN that can not XSS you: Using Subresource Integrity
  14. The Twitter Gazebo
  15. German Firefox 1.0 ad (OCR)
  16. My thoughts on Tor appliances
  17. Subresource Integrity
  18. Revoke App Permissions on Firefox OS
  19. (Self) XSS at Mozilla's internal Phonebook
  20. Tales of Python's Encoding
  21. On the X-Frame-Options Security Header
  22. html2dom
  23. Security Review: HTML sanitizer in Thunderbird
  24. Week 29 2013
  25. The First Post