index.rst (3106B)
1 ========================= 2 moz-cached-ohttp Protocol 3 ========================= 4 5 The ``moz-cached-ohttp://`` protocol handler enables Firefox to load resources over Oblivious HTTP (OHTTP) 6 from privileged contexts, including in the privileged about content process. This mechanism provides 7 privacy-preserving resource loading, and was originally designed for loading images in about:newtab. 8 9 .. toctree:: 10 :maxdepth: 2 11 12 usage 13 api 14 15 Overview 16 ======== 17 18 The moz-cached-ohttp protocol implements a cache-first strategy that: 19 20 1. First attempts to load resources from the HTTP cache to minimize OHTTP requests 21 2. Falls back to loading via OHTTP when resources are not available in cache 22 3. Automatically caches OHTTP responses for future requests 23 4. Respects HTTP cache expiration headers for proper cache management, but 24 otherwise defaults to 24 hours for the cache expiry. 25 26 Supported Contexts 27 ================== 28 29 The protocol is restricted to specific contexts for security: 30 31 * **Privileged about content process**: Primary use case is for privacy-preserving image loading on about:newtab 32 * **System principals in parent process**: For tests and internal usage 33 34 URL Format 35 ========== 36 37 The protocol uses a specific URL format to encode the target resource URL: 38 39 .. code-block:: 40 41 moz-cached-ohttp://newtab-image/?url=<encoded-url> 42 43 Where ``<encoded-url>`` is the URL-encoded target **HTTPS-only** image URL. 44 45 .. note:: 46 Only the ``newtab-image`` host is currently supported. The host determines which OHTTP configuration and relay will be used for the request. See ``HOST_MAP`` in ``MozCachedOHTTPProtocolHandler.sys.mjs``. 47 48 .. warning:: 49 50 Only HTTPS target URLs are supported for security. HTTP URLs will be rejected. 51 52 Example: 53 54 .. code-block:: 55 56 moz-cached-ohttp://newtab-image/?url=https%3A%2F%2Fexample.com%2Fimage.jpg 57 58 .. note:: 59 60 The OHTTP Relay and Gateway must both be configured to enable requests. The OHTTP Gateway also needs to have an allowlist that includes the resource endpoint, otherwise requests are likely to return ``403 Forbidden`` responses. 61 62 Host-Based Configuration 63 ======================== 64 65 The protocol uses a host-based configuration system that maps URL hosts to specific OHTTP settings. This design allows different types of resource requests to use different OHTTP configurations in the future. 66 67 Currently Supported Hosts 68 -------------------------- 69 70 * **newtab-image**: Used for New Tab page image loading 71 72 * Gateway Config URL preference: ``browser.newtabpage.activity-stream.discoverystream.ohttp.configURL`` 73 * Relay URL preference: ``browser.newtabpage.activity-stream.discoverystream.ohttp.relayURL`` 74 75 Future Extensibility 76 -------------------- 77 78 The host-based design allows easy addition of new hosts with different OHTTP configurations: 79 80 .. code-block:: javascript 81 82 // Future hosts could be added like: 83 // moz-cached-ohttp://other-service/?url=<encoded-url> 84 // moz-cached-ohttp://ads-service/?url=<encoded-url> 85 86 Each host would map to its own set of configuration preferences, allowing different services to use different OHTTP infrastructure.