341 lines
22 KiB
HTML
341 lines
22 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="/mask-icon.svg" color="#1a1a1a"/>
|
|
<link rel="stylesheet" href="/grapheneos.css?16"/>
|
|
<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="/faq">FAQ</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>This is a guide covering some aspects of using GrapheneOS. It's not intended to be
|
|
an overview of the privacy and security features implemented by GrapheneOS. It will
|
|
only cover the user-facing impact of features, and most of the privacy and security
|
|
work is done under the hood.</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>
|
|
<li><a href="#updates-sideloading">Sideloading</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#web-browsing">Web browsing</a></li>
|
|
<li><a href="#camera">Camera</a></li>
|
|
<li><a href="#exec-spawning">Exec spawning</a></li>
|
|
<li><a href="#bugs-uncovered-by-security-features">Bugs uncovered by security features</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 "Check for updates" option will manually trigger an update check as soon as
|
|
possible. It will still wait for the configuration conditions listed below to be
|
|
satisfied, such as being connected to the internet via one of the permitted network
|
|
types.</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>
|
|
|
|
<h3 id="updates-sideloading">
|
|
<a href="#updates-sideloading">Sideloading</a>
|
|
</h3>
|
|
|
|
<p>Updates can be downloaded via
|
|
<a href="https://grapheneos.org/releases">the releases page</a> and installed via recovery
|
|
with adb sideloading. The zip files are signed and verified by recovery, just as they
|
|
are by the update client within the OS. This includes providing downgrade protection,
|
|
which prevents attempting to downgrade the version. If recovery didn't enforce these
|
|
things, they would still be enforced via verified boot including downgrade protection
|
|
on modern devices (Pixel 2 and later) and the attempted update would just fail to boot
|
|
and be rolled back.</p>
|
|
|
|
<p>To install one by sideloading, first, boot into recovery. You may do this either by
|
|
using <code>adb reboot recovery</code> from the operating system, or by selecting the
|
|
"Recovery" option in the bootloader menu.</p>
|
|
|
|
<p>You should see the green Android lying on its back being repaired, with the text "No
|
|
command" meaning that no command has been passed to recovery.</p>
|
|
|
|
<p>Next, access the recovery menu by holding down the power button and pressing the volume
|
|
up button a single time. This key combination toggles between the GUI and text-based mode
|
|
with the menu and log output.</p>
|
|
|
|
<p>Finally, select the "Apply update from ADB" option in the recovery menu and
|
|
sideload the update with adb. For example:</p>
|
|
|
|
<pre>adb sideload blueline-ota_update-2019.07.01.21.zip</pre>
|
|
|
|
<p><strong>You do not need to have adb enabled within the OS or the host's ADB key
|
|
whitelisted within the OS to sideload an update to recovery. Recovery mode does not
|
|
trust the attached computer and this can be considered a production feature. Trusting
|
|
a computer with ADB access within the OS is much different and exposes the device to a
|
|
huge amount of attack surface and control by the trusted computer.</strong></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. 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 (GeckoView is not 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>
|
|
|
|
<h2 id="camera">
|
|
<a href="#camera">Camera</a>
|
|
</h2>
|
|
|
|
<p>The Camera app included in GrapheneOS is very basic and can't take full advantage
|
|
of the hardware. It doesn't offer much in the way of configuration. In the long term,
|
|
it's going to be replaced. In the short term, there are other apps available providing
|
|
more capabilities and better support for taking advantage of the hardware.</p>
|
|
|
|
<p>The Pixel 2 and Pixel 3 (but not the Pixel 3a) have a Pixel Visual Core providing
|
|
a hardware-based implementation of HDR+. HDR+ captures many images and intelligently
|
|
merges data across them, taking into account motion, etc. It substantially improves
|
|
the quality of images, especially in low light. This is used transparently for third
|
|
party apps that are compatible with it, and there isn't an explicit switch to turn it
|
|
on or off for most of them. An example of a compatible app is Open Camera's default
|
|
configuration, or Open Camera with the Camera 2 API and other settings (including the
|
|
the various knobs / toggles outside of the settings menu) left alone. In general, HDR+
|
|
will work transparently in most apps as long as they keep things simple and use a good
|
|
minimalist approach to taking pictures. It should work transparently in most messaging
|
|
apps, etc. with internal support for taking pictures.</p>
|
|
|
|
<p>In addition to supporting HDR+ via the Pixel Visual Core, or similar features on
|
|
other devices with the same constraints, Open Camera offers advanced configuration and
|
|
various advanced features. Make sure to enable the Camera 2 API in the settings, which
|
|
should be the default, but the app doesn't have a great user interface / user
|
|
experience. You probably don't want to use the traditional HDR feature in the app.
|
|
That's not HDR+, but rather captures 3 images and merges them in a way that isn't at
|
|
all intelligent and causes a lot of blur and distortion. The HDR+ implementation can
|
|
actually benefit from the camera not being completely steady as it's smart enough to
|
|
match up the picture and it provides it with more data vs. a traditional HDR
|
|
implementation where it essentially doesn't work without a tripod and is not really at
|
|
all useful on a phone unless you actually have that for it.</p>
|
|
|
|
<h2 id="exec-spawning">
|
|
<a href="#exec-spawning">Exec spawning</a>
|
|
</h2>
|
|
|
|
<p>You may notice that cold start app spawning time takes a bit longer (i.e. in the
|
|
ballpark of 100ms) than stock Android, along with higher app memory usage. This is due
|
|
to security centric exec spawning model used by GrapheneOS to provide each application
|
|
with a unique address space layout, random hardened_malloc heap layout and unique keys
|
|
/ seeds for other probabilistic exploit mitigations like stack canaries, setjmp
|
|
protection and future features like randomized memory tags. Exec spawning doesn't
|
|
cause a performance cost after launching an app, and similarly doesn't cause any extra
|
|
latency for app spawning if the app was already running / cached in the background. It
|
|
isn't very noticeable on flagship devices with a high end CPU like a Pixel 3, and is a
|
|
lot more noticeable on a lower end device like a Pixel 3a.</p>
|
|
|
|
<h2 id="bugs-uncovered-by-security-features">
|
|
<a href="#bugs-uncovered-by-security-features">Bugs uncovered by security features</a>
|
|
</h2>
|
|
|
|
<p>GrapheneOS substantially expands the standard mitigations for memory corruption
|
|
vulnerabilities. Some of these features are designed to directly catch the memory
|
|
corruption bugs either via an explicit check or memory protection and abort the
|
|
program in order to prevent them from being exploited. Other features mitigate issues
|
|
a bit less directly such as zeroing data immediately upon free, isolated memory
|
|
regions, heap randomization, etc. and can also lead to latent memory corruption bugs
|
|
crashing instead of the program continuing onwards with corrupted memory. This means
|
|
that many latent memory corruption bugs in apps are caught along with some in the OS
|
|
itself. These bugs are not caused by GrapheneOS, but rather already existed and are
|
|
uncovered by the features. The features are aimed at preventing or hindering exploits,
|
|
not finding bugs, but they do that as part of doing their actual job.</p>
|
|
|
|
<p>Similarly, some of the other privacy and security improvements reduce the access
|
|
available to applications and they may crash. Some of these features are always
|
|
enabled under the hood, while others like the Network and Sensors toggles are
|
|
controlled by users via opt-in or opt-out toggles. Apps may not handle having access
|
|
taken away like this, although it generally doesn't cause any issues as it's all
|
|
designed to be friendly to apps and fully compatible rather than killing the
|
|
application when it violates the rules.</p>
|
|
|
|
<p>If you run into an application aborting, try to come up with a process for
|
|
reproducing the issue and then capture a bug report via the 'Take bug report' feature
|
|
in Developer options. Report an issue to the GrapheneOS OS issue tracker and email the
|
|
bug report capture zip to contact@grapheneos.org with the issue tracker number in the
|
|
subject like "Bug report capture for issue #104". The bug report capture includes
|
|
plain text 'tombstones' with logs, tracebacks, address space layout, register content
|
|
and a tiny bit of context from memory from areas that are interesting for debugging.
|
|
This may contain some sensitive data. Feel free to provide only the tombstone for the
|
|
relevant crash and filter out information you don't want to send. However, it will be
|
|
more difficult to debug if you provide less of the information. If the app doesn't
|
|
work with sensitive information, just send the whole tombstone.</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>
|
|
<li><a href="https://reddit.com/r/GrapheneOS">Reddit</a></li>
|
|
</ul>
|
|
</footer>
|
|
<script src="/redirect.js?5"></script>
|
|
</body>
|
|
</html>
|