Usage
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.
Table of contents
Auditor
See the tutorial page on the site for the attestation sub-project.
Updates
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.
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.
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.
Release changelogs are available in a section on the releases page.
Settings
The settings are available in the Settings app in System ➔ Advanced ➔ Update settings.
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.
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.
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.
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.
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.
Security
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.
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.
Disabling
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.
Sideloading
Updates can be downloaded via the releases page 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.
To install one by sideloading, first, boot into recovery. You may do this either by
using adb reboot recovery from the operating system, or by selecting the
"Recovery" option in the bootloader menu.
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.
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.
Finally, select the "Apply update from ADB" option in the recovery menu and sideload the update with adb. For example:
adb sideload blueline-ota_update-2019.07.01.21.zip
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.
Web browsing
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.
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.
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.
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 isolatedProcess
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.
Camera
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.
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.
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.
Exec spawning
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.
Bugs uncovered by security features
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.
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.
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.
Wi-Fi privacy
Wi-Fi on GrapheneOS is very privacy-friendly and is essentially anonymous as long as apps do not leak uniquely identifying information to the network. GrapheneOS avoids allowing itself to be fingerprinted as GrapheneOS, other than connections which are documented (see the FAQ) and can be easily disabled or forced through a VPN service.
Scanning
MAC randomization is always performed for Wi-Fi scanning. Pixel phones have firmware support for scanning MAC randomization going significantly beyond a naive implementation. On many other devices, there are identifiers exposed by Wi-Fi scanning beyond the MAC address such as the packet sequence number and assorted identifying information in the probe requests.
Avoid using hidden APs (i.e. APs not broadcasting their SSID) since known hidden SSIDs end up being broadcast to find them again. SSIDs are not broadcast for standard non-hidden APs.
Wi-Fi and Bluetooth scanning for improving location detection are disabled by default, unlike the stock OS. These can be toggled in Settings ➔ Location ➔ Wi-Fi and Bluetooth scanning. These features enable scanning even when Wi-Fi or Bluetooth is disabled, so these need to be kept disabled to fully disable the radios when Wi-Fi and Bluetooth are disabled. GrapheneOS doesn't yet have an implementation of a coarse location service to supplement GPS location, so enabling these options doesn't actually do anything at the moment. Implementing a supplementary location service is planning but we need a robust, secure and private implementation via a local database. The initial focus will likely be a cell phone tower database, so these features still wouldn't be relevant.
Associated with an Access Point (AP)
The DHCP client uses the anonymity profile rather than sending a hostname so it doesn't compromise the privacy offered by MAC randomization.
Associated MAC randomization is performed by default. This can be controlled per-network with Settings ➔ Network & Internet ➔ Wi-Fi ➔ <network> ➔ Advanced ➔ Privacy.
In the stock OS, the default is to use a unique persistent random MAC address for each network. It has 2 options available: "Use randomized MAC (default)" and "Use device MAC". In GrapheneOS, the default is generating a new random MAC address when connecting to a network. It has 3 options available: "Use per-connection randomized MAC (default)", "Use per-network randomized MAC" and "Use device MAC".