index.rst (5207B)
1 ============================ 2 Web Security Checks in Gecko 3 ============================ 4 5 Key Concepts and Terminology 6 ============================= 7 8 Security Principal (nsIPrincipal) 9 --------------------------------- 10 11 A Security Principal represents the security context for a piece of code or data. Firefox uses four types of principals: 12 13 - **ContentPrincipal**: Used for typical web pages and can be serialized to an origin URL, e.g., https://example.com/. 14 - **NullPrincipal**: Used for pages that are never same-origin with anything else, such as iframes with the sandbox attribute or documents loaded with a data: URI. This is also known as an opaque origin. 15 - **SystemPrincipal**: Used for the browser's user interface, commonly referred to as "browser chrome", and various other background services (OCSP requests, fetching favicons). Pages like about:preferences use the SystemPrincipal. 16 - **ExpandedPrincipal**: Used by browser extensions that need to assume the security context of a website. An ExpandedPrincipal is best understood as a list of principals. 17 18 OriginAttributes 19 ---------------------------- 20 21 `OriginAttributes` help in managing and enforcing security policies by distinguishing different security contexts that might otherwise be considered the same based on their Principal. They are used to: 22 23 - Isolate data and resources in private browsing mode. 24 - Implement cache isolation. 25 - Manage user context identifiers for container tabs. 26 - Enforce first-party isolation. 27 28 Attributes 29 ---------- 30 31 The `OriginAttributes` class extends the functionality of `dom::OriginAttributesDictionary` and includes additional methods for setting and managing various attributes. 32 33 Key attributes include: 34 35 - **FirstPartyDomain**: Used to isolate data based on the domain. 36 - **UserContextId**: Identifies different user contexts, such as container tabs. 37 - **PrivateBrowsingId**: Indicates whether a request is made in private browsing mode. 38 - **PartitionKey**: Used to implement cache isolation. 39 40 41 Load Info Object (nsILoadInfo) 42 ------------------------------ 43 44 The `nsILoadInfo` object is crucial for security checks. It holds all security-relevant attributes, including security flags indicating what checks need to be performed and the associated Principal. 45 46 Attributes: 47 ----------- 48 49 - `loadingPrincipal`: The principal of the document where the result of the load will be used. 50 - `triggeringPrincipal`: The principal that triggered the URL to load. 51 - `securityFlags`: Indicate the type of security checks required. 52 - `contentPolicyType`: Specifies the type of content being loaded, used for security checks like Content Security Policy. 53 54 Loading Lifecycle in Firefox 55 ============================ 56 57 From Request to Response 58 ------------------------ 59 60 1. **Request Initiation**: A web page initiates a request. 61 2. **nsIChannel Creation**: Firefox creates an `nsIChannel` object, representing the request. 62 3. **nsILoadInfo Attachment**: An `nsILoadInfo` object is required for the creation of an `nsIChannel` and holds security-related information. 63 4. **Security Checks**: Security checks are performed using the `ContentSecurityManager`. 64 5. **Request Execution**: If all checks pass, the request proceeds. 65 66 Role of nsIChannel and nsILoadInfo 67 ---------------------------------- 68 69 - **nsIChannel**: Manages the transport algorithm (e.g., HTTP, WebSocket). 70 - **nsILoadInfo**: Holds security relevant meta information of a network load and determines what security checks need to be enforced. 71 72 73 Security Checks During Loading 74 ============================== 75 76 Pre-Request Checks 77 ------------------ 78 79 - **Same-Origin Policy**: Ensures resources are only accessed if they share the same origin. 80 - **Content Security Policy**: Enforces content restrictions based on policies defined by the site. 81 - **Mixed Content Blocking**: Implements the Mixed Content standard, including blocking and upgrading of insecure (HTTP) content on secure (HTTPS) pages. 82 83 ContentSecurityManager and doContentSecurityCheck() 84 --------------------------------------------------- 85 86 - **ContentSecurityManager**: Centralized manager for performing security checks. 87 - **PerformSecurityCheck()**: Key function that is invoked to perform all relevant security checks before a request is executed. 88 89 Subsumes Concept 90 ---------------- 91 92 - **Definition**: A principal subsumes another if it has access to the same resources. 93 - **Implementation**: `aPrincipal->Subsumes(aOtherPrincipal)` is used to check access permissions. 94 95 Code example:: 96 97 bool subsumes = principal1->Subsumes(principal2); 98 99 Subsumption is asymmetrical. One principal subsuming the other does not imply the inverse. A typical example is the `SystemPrincipal`, which subsumes all other 100 principals. 101 102 References 103 ---------- 104 The interface definition in source code have a lot of detailed comments: 105 106 - The `nsIPrincipal <https://searchfox.org/mozilla-central/source/caps/nsIPrincipal.idl>`_ interface definition. 107 - The `nsILoadInfo <https://searchfox.org/mozilla-central/source/netwerk/base/nsILoadInfo.idl>`_ interface definition. 108 - The `nsIContentSecurityManager <https://searchfox.org/mozilla-central/source/dom/interfaces/security/nsIContentSecurityManager.idl>`_ interface definition