1503d660d2
The approach of using 100vh interacts poorly with how Chromium and Safari calculate the viewport height on mobile. They include their navigation bar as part of the viewport height from the start to avoid dynamic changes to the viewport site.
272 lines
16 KiB
HTML
272 lines
16 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" prefix="og: http://ogp.me/ns#">
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<title>Usage | GrapheneOS</title>
|
|
<meta name="description" content="Usage instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta name="theme-color" content="#212121"/>
|
|
<meta name="msapplication-TileColor" content="#ffffff"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<meta name="twitter:site" content="@GrapheneOS"/>
|
|
<meta name="twitter:creator" content="@GrapheneOS"/>
|
|
<meta property="og:title" content="GrapheneOS usage documentation"/>
|
|
<meta property="og:description" content="Usage instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta property="og:type" content="website"/>
|
|
<meta property="og:image" content="https://grapheneos.org/opengraph.png"/>
|
|
<meta property="og:image:width" content="512"/>
|
|
<meta property="og:image:height" content="512"/>
|
|
<meta property="og:image:alt" content="GrapheneOS logo"/>
|
|
<meta property="og:url" content="https://grapheneos.org/usage"/>
|
|
<meta property="og:site_name" content="GrapheneOS"/>
|
|
<link rel="icon" type="image/vnd.microsoft.icon" href="/favicon.ico"/>
|
|
<link rel="mask-icon" href="/safari_pinned_tab_icon.svg" color="#000000"/>
|
|
<link rel="stylesheet" href="/grapheneos.css?13"/>
|
|
<link rel="manifest" href="/manifest.webmanifest"/>
|
|
<link rel="canonical" href="https://grapheneos.org/usage"/>
|
|
</head>
|
|
<body>
|
|
<nav>
|
|
<ul>
|
|
<li><a href="/">GrapheneOS</a></li>
|
|
<li><a href="/install">Install</a></li>
|
|
<li><a href="/build">Build</a></li>
|
|
<li class="active"><a href="/usage">Usage</a></li>
|
|
<li><a href="/releases">Releases</a></li>
|
|
<li><a href="/source">Source</a></li>
|
|
<li><a href="/donate">Donate</a></li>
|
|
<li><a href="/contact">Contact</a></li>
|
|
</ul>
|
|
</nav>
|
|
<div id="content">
|
|
<h1 id="usage">
|
|
<a href="#usage">Usage</a>
|
|
</h1>
|
|
<p><strong>This guide is still very new and will be filled with lots of additional
|
|
content over time.</strong></p>
|
|
|
|
<h2 id="table-of-contents">
|
|
<a href="#table-of-contents">Table of contents</a>
|
|
</h2>
|
|
<ul>
|
|
<li><a href="#auditor">Auditor</a></li>
|
|
<li>
|
|
<a href="#updates">Updates</a>
|
|
<ul>
|
|
<li><a href="#updates-settings">Settings</a></li>
|
|
<li><a href="#updates-security">Security</a></li>
|
|
<li><a href="#updates-disabling">Disabling</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#default-connections">Default connections</a></li>
|
|
<li><a href="#web-browsing">Web browsing</a></li>
|
|
</ul>
|
|
|
|
<h2 id="auditor">
|
|
<a href="#auditor">Auditor</a>
|
|
</h2>
|
|
<p>See the <a href="https://attestation.app/tutorial">tutorial page on the site for the attestation sub-project</a>.</p>
|
|
|
|
<h2 id="updates">
|
|
<a href="#updates">Updates</a>
|
|
</h2>
|
|
|
|
<p>The update system implements automatic background updates. It checks for updates
|
|
approximately once every four hours when there's network connectivity and then
|
|
downloads and installs updates in the background. It will pick up where it left off if
|
|
downloads are interrupted, so you don't need to worry about interrupting it.
|
|
Similarly, interrupting the installation isn't a risk because updates are installed to
|
|
a secondary installation of GrapheneOS which only becomes the active installation
|
|
after the update is complete. Once the update is complete, you'll be informed with a
|
|
notification and simply need to reboot with the button in the notification or via a
|
|
normal reboot. If the new version fails to boot, the OS will be rolled back to the
|
|
past version and the updater will attempt to download and install the update
|
|
again.</p>
|
|
|
|
<p>The updater will use incremental (delta) updates to download only changes rather
|
|
than the whole OS when one is available to go directly from the installed version to
|
|
the latest version. As long as you have working network connectivity on a regular
|
|
basis and reboot when asked, you'll almost always be on one of the past couple
|
|
versions of the OS which will minimize bandwidth usage since incrementals will always
|
|
be available.</p>
|
|
|
|
<p>The updater works while the device is locked / idle, including before the first
|
|
unlock since it's explicitly designed to be able to run before decryption of user
|
|
data.</p>
|
|
|
|
<p>Release changelogs are available <a href="/releases#changelog">in a section on the releases page</a>.</p>
|
|
|
|
<h3 id="updates-settings">
|
|
<a href="#updates-settings">Settings</a>
|
|
</h3>
|
|
|
|
<p>The settings are available in the Settings app in System ➔ Advanced ➔ Update
|
|
settings.</p>
|
|
|
|
<p>The "Release channel" setting can be changed from the default Stable channel to the
|
|
Beta channel if you want to help with testing. The Beta channel will usually simply
|
|
follow the Stable channel, but the Beta channel may be used to experiment with new
|
|
features.</p>
|
|
|
|
<p>The "Permitted networks" setting controls which networks will be used to perform
|
|
updates. It defaults to using any network connection. It can be set to "Non-roaming"
|
|
to disable it when the cellular service is marked as roaming or "Unmetered" to disable
|
|
it on cellular networks and also Wi-Fi networks marked as metered.</p>
|
|
|
|
<p>The "Require battery above warning level" setting controls whether updates will
|
|
only be performed when the battery is above the level where the warning message is
|
|
shown. The standard value is at 15% capacity.</p>
|
|
|
|
<p>Enabling the opt-in "Automatic reboot" setting allows the updater to reboot the
|
|
device after an update once it has been idle for a long time. When this setting is
|
|
enabled, a device can take care of any number of updates completely automatically even
|
|
if it's left completely idle.</p>
|
|
|
|
<h3 id="updates-security">
|
|
<a href="#updates-security">Security</a>
|
|
</h3>
|
|
|
|
<p>The update server isn't a trusted party since updates are signed and verified along
|
|
with downgrade attacks being prevented. The update protocol doesn't send identifiable
|
|
information to the update server and works well over a VPN / Tor. GrapheneOS isn't
|
|
able to comply with a government order to build, sign and ship a malicious update to a
|
|
specific user's device based on information like the IMEI, serial number, etc. The
|
|
update server only ends up knowing the IP address used to connect to it and the
|
|
version being upgraded from based on the requested incremental.</p>
|
|
|
|
<p>Android updates can support serialno constraints to make them validate only on a
|
|
certain device but GrapheneOS rejects any update with a serialno constraint for both
|
|
the Stable and Beta channels.</p>
|
|
|
|
<h3 id="updates-disabling">
|
|
<a href="#updates-disabling">Disabling</a>
|
|
</h3>
|
|
|
|
<p>It's highly recommended to leave automatic updates enabled and to configure the
|
|
permitted networks if the bandwidth usage is a problem on your mobile data connection.
|
|
However, it's possible to turn off the update client by going to Settings ➔ Apps,
|
|
enabling Show system via the menu, selecting Seamless Update Client and disabling the
|
|
app. If you do this, you'll need to remember to enable it again to start receiving
|
|
updates.</p>
|
|
|
|
<h2 id="default-connections">
|
|
<a href="#default-connections">Default connections</a>
|
|
</h2>
|
|
|
|
<p>GrapheneOS makes connections to the outside world to test connectivity, detect
|
|
captive portals and download updates. No data varying per user / installation is sent
|
|
in these connections. There aren't analytics / telemetry in GrapheneOS.</p>
|
|
|
|
<p>The expected default connections by GrapheneOS (including all base system apps) are the following:</p>
|
|
|
|
<ul>
|
|
<li>
|
|
<p>The GrapheneOS Updater app fetches update metadata from
|
|
https://releases.grapheneos.org/DEVICE-CHANNEL approximately once every four hours
|
|
when connected to a permitted network for updates.</p>
|
|
<p>Users can control which types of connections the Updater app will use, and
|
|
although it's strongly recommended to always leave it enabled it can be
|
|
disabled.</p>
|
|
</li>
|
|
<li>
|
|
<p>On devices with a Qualcomm baseband (which provides GPS), when location
|
|
functionality is being used,
|
|
<a href="https://en.wikipedia.org/wiki/GPS_signals#Almanac">GPS almanacs</a>
|
|
are downloaded from https://xtrapath1.izatcloud.net/xtra3grc.bin,
|
|
https://xtrapath2.izatcloud.net/xtra3grc.bin or
|
|
https://xtrapath3.izatcloud.net/xtra3grc.bin. GrapheneOS has modified all
|
|
references to these servers to use HTTPS rather than a mix of HTTP and HTTPS.</p>
|
|
</li>
|
|
<li>
|
|
<p>Connectivity checks designed to mimic a web browser user agent are performed
|
|
by using HTTP and HTTPS to fetch standard URLs generating an HTTP 204 status
|
|
code. This is used to detect when internet connectivity is lost on a network,
|
|
which triggers fallback to other available networks if possible. These checks
|
|
are designed to detect and handle captive portals which substitute the
|
|
expected empty 204 response with their own web page. These need use a very
|
|
common domain and URL in order to bypass whitelisting systems only permitting
|
|
access to common domains / URLs so a domain like grapheneos.org would likely
|
|
be inadequate. GrapheneOS leaves these set to the standard four URLs to blend
|
|
into the crowd of billions of other Android devices with and without Google
|
|
Mobile Services performing the same empty GET requests. For privacy reasons,
|
|
it isn't desirable to stand out from the crowd and changing these URLs or even
|
|
disabling the feature will likely reduce your privacy by giving your device a
|
|
more unique fingerprint. GrapheneOS aims to appear like any other common
|
|
mobile device on the network.</p>
|
|
<ul>
|
|
<li>HTTPS: https://www.google.com/generate_204</li>
|
|
<li>HTTP: http://connectivitycheck.gstatic.com/generate_204</li>
|
|
<li>HTTP fallback: http://www.google.com/gen_204</li>
|
|
<li>HTTP other fallback: http://play.googleapis.com/generate_204</li>
|
|
</ul>
|
|
<p>Standard AOSP user agent for the GET request:</p>
|
|
<p>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.32 Safari/537.36</p>
|
|
<p>No query / data is sent and the response is unused beyond checking the response code.</p>
|
|
</li>
|
|
<li>
|
|
<p>DNS connectivity and functionality tests</p>
|
|
</li>
|
|
<li>
|
|
<p>DNS resolution for other connections</p>
|
|
</li>
|
|
</ul>
|
|
|
|
<p>Similar connectivity checks are also performed by the hardened Chromium browser (Vanadium).</p>
|
|
|
|
<h2 id="web-browsing">
|
|
<a href="#web-browsing">Web browsing</a>
|
|
</h2>
|
|
|
|
<p>GrapheneOS includes a Vanadium subproject providing privacy and security enhanced
|
|
releases of Chromium. Vanadium is both the user-facing browser included in the OS and
|
|
the provider of the WebView used by other apps to render web content. The WebView is
|
|
the browser engine used by the vast majority of web browsers and nearly all other apps
|
|
embedding web content or using web technologies for other uses.</p>
|
|
|
|
<p>Using Vanadium is highly recommended and Bromite is a good alternative if you want
|
|
a few more features like ad-blocking and more aggressive anti-fingerprinting. Vanadium
|
|
is working towards including these features and is actively collaborating with
|
|
Bromite. Other Chromium-based browsers like Brave can also be decent choices.
|
|
Standalone browsers based on Chromium have by far the best sandbox implementation.
|
|
Site isolation can also be enabled, which makes the sandbox enforce a security
|
|
boundary containing each site rather than isolating content as a whole. Vanadium
|
|
enables site isolation by default, and Bromite enables it on high memory devices,
|
|
including all officially supported GrapheneOS devices. Site isolation prevents an
|
|
attacker from obtaining cookies (like login sessions) and other data tied to other
|
|
sites if they successfully exploit the browser's rendering engine. It also provides
|
|
the strongest available mitigation for Spectre-based side channel attacks.</p>
|
|
|
|
<p>WebView-based browsers use the hardened Vanadium rendering engine, but they can't
|
|
offer as much privacy and control due to being limited to the capabilities supported
|
|
by the WebView widget. For example, they can't provide a setting for toggling sensors
|
|
access because the feature is fairly new and the WebView WebSettings API doesn't yet
|
|
include support for it as it does for JavaScript, location, cookies, DOM storage and
|
|
other older features. For sensors, the Sensors app permission added by GrapheneOS can
|
|
be toggled off for the browser app as a whole instead. The WebView sandbox also
|
|
currently runs every instance within the same process and doesn't support site
|
|
isolation.</p>
|
|
|
|
<p>Avoid Gecko-based browsers like Firefox as they're currently much more vulnerable
|
|
to exploitation and inherently add a huge amount of attack surface. Gecko doesn't have
|
|
a WebView implementation, so it has to be used alongside the Chromium-based WebView
|
|
rather than instead of Chromium, which means having the remote attack surface of two
|
|
separate browser engines instead of only one. Firefox / Gecko also bypass or cripple a
|
|
fair bit of the upstream and GrapheneOS hardening work for apps. Worst of all, Firefox
|
|
runs as a single process on mobile and has no sandbox beyond the OS sandbox. This is
|
|
despite the fact that Chromium semantic sandbox layer on Android is implemented via
|
|
the OS <code>isolatedProcess</code> feature, which is a very easy to use boolean
|
|
property for app service processes to provide strong isolation with only the ability
|
|
to communicate with the app running them via the standard service API. Even in the
|
|
desktop version, Firefox's sandbox is still substantially weaker (especially on Linux,
|
|
where it can hardly be considered a sandbox at all) and lacks support for isolating
|
|
sites from each other rather than only containing content as a whole.</p>
|
|
</div>
|
|
<footer>
|
|
<a href="/"><img src="https://grapheneos.org/logo.png" width="512" height="512" alt=""/>GrapheneOS</a>
|
|
<ul id="social">
|
|
<li><a href="https://twitter.com/GrapheneOS">Twitter</a></li>
|
|
<li><a href="https://github.com/GrapheneOS">GitHub</a></li>
|
|
</ul>
|
|
</footer>
|
|
</body>
|
|
</html>
|