208 lines
12 KiB
HTML
208 lines
12 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="viewport" content="width=device-width, initial-scale=1"/>
|
|
<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/x-icon" href="/favicon.ico?0"/>
|
|
<link rel="mask-icon" href="/safari_pinned_tab_icon.svg" color="#000000"/>
|
|
<link rel="stylesheet" href="/grapheneos.css?8"/>
|
|
<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">Usage</h1>
|
|
<p><strong>This guide is still very new and will be filled with lots of additional
|
|
content over time.</strong></p>
|
|
|
|
<h2 id="auditor">
|
|
Auditor
|
|
<a href="#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">
|
|
Updates
|
|
<a href="#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">
|
|
Settings
|
|
<a href="#updates-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">
|
|
Security
|
|
<a href="#updates-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">
|
|
Disabling
|
|
<a href="#updates-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">
|
|
Default connections
|
|
<a href="#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://seamlessupdate.app/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>
|
|
</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>
|