Skip to content

Instantly share code, notes, and snippets.

@mozfreddyb

mozfreddyb/principals-reference.md

Last active August 3, 2020 11:29
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save mozfreddyb/50cdf08de446898633ff39ec826db710 to your computer and use it in GitHub Desktop.
Save mozfreddyb/50cdf08de446898633ff39ec826db710 to your computer and use it in GitHub Desktop.
Download ZIP
reference sheet for principals in mozilla code
Raw
principals-reference.md

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment