Usage

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.

adb sideload blueline-ota_update-2019.07.01.21.zip

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. Bromite is a solid alternative and is the only other browser we recommend. Bromite provides integrated ad-blocking and more advanced anti-fingerprinting. For now, Vanadium is more focused on security hardening and Bromite is more focused on anti-fingerprinting. The projects are collaborating together and will likely converge to providing more of the same features. Vanadium will be providing content filtering and anti-fingerprinting, but it needs to be done in a way that meets the standards of the project, which takes time.

Vanadium is designed for use on GrapheneOS and does not duplicate the OS privacy and security features such as the hardened malloc implementation. This leads to some of the differences from Bromite, such as relying on OS support for encrypted DNS rather than enabling Chromium's DNS-over-HTTPS support.

Chromium-based browsers like Vanadium and Bromite provide the strongest sandbox implementation, leagues ahead of the alternatives. It is much harder to escape from the sandbox and it provides much more than acting as a barrier to compromising the rest of the OS. Site isolation enforces security boundaries around each site using the sandbox by placing each site into an isolated sandbox. It required a huge overhaul of the browser since it has to enforce these rules on all the IPC APIs. Site isolation is important even without a compromise, due to side channels. Browsers without site isolation are very vulnerable to attacks like Spectre. On mobile, due to the lack of memory available to apps, there are different modes for site isolation. Vanadium turns on strict site isolation, matching Chromium on the desktop. Bromite enables strict site isolation on high memory devices, including all the devices that are officially supported by GrapheneOS.

Chromium has decent exploit mitigations, unlike the available alternatives. This is improved upon in Vanadium by enabling further mitigations, including those developed upstream but not yet fully enabled due to code size, memory usage or performance. For example, it enables type-based CFI like Chromium on the desktop, uses a stronger SSP configuration, zero initializes variables by default, etc. Some of the mitigations are inherited from the OS itself, which also applies to other browsers, at least if they don't do things to break them.

We recommend against trying to achieve browser privacy and security through piling on browser extensions and modifications. Most privacy features for browsers are privacy theater without a clear threat model and these features often reduce privacy by aiding fingerprinting and adding more state shared between sites. Every change you make results in you standing out from the crowd and generally provides more ways to track you. Enumerating badness via content filtering is not a viable approach to achieving decent privacy, just as AntiVirus isn't a viable way to achieving decent security. These are losing battles, and are at best a stopgap reducing exposure while waiting for real privacy and security features.

Vanadium will be following the school of thought where hiding the IP address through Tor or a trusted VPN shared between many users is the essential baseline, with the browser partitioning state based on site and mitigating fingerprinting to avoid that being trivially bypassed. The Tor Browser's approach is the only one with any real potential, however flawed the current implementation may be. This work is currently in a very early stage and it is largely being implemented upstream with the strongest available implementation of state partitioning. Chromium is using Network Isolation Keys to divide up connection pools, caches and other state based on site and this will be the foundation for privacy. Chromium itself aims to prevent tracking through mechanisms other than cookies, greatly narrowing the scope downstream work needs to cover. Bromite is doing a lot of work in these areas and Vanadium will be benefiting from that along with this upstream work. The focus is currently on research since we don't see much benefit in deploying bits and pieces of this before everything is ready to come together. At the moment, the only browser with any semblance of privacy is the Tor Browser but there are many ways to bypass the anti-fingerprinting and state partitioning. The Tor Browser's security is weak which makes the privacy protection weak. The need to avoid diversity (fingerprinting) creates a monoculture for the most interesting targets. This needs to change, especially since Tor itself makes people into much more of a target (both locally and by the exit nodes).

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 sandbox 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 3 (but not the Pixel 3a) and Pixel 4 (but not the Pixel 4a) have a Pixel Visual Core / Pixel Neural 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

GrapheneOS creates fresh processes (via exec) when spawning applications instead of using the traditional Zygote spawning model. This improves privacy and security at the expense of higher cold start app spawning time and higher initial memory usage. It doesn't impact runtime performance beyond the initial spawning time. It adds somewhere in the ballpark of 100ms to app spawning time on the flagship devices and is only very noticeable on lower-end devices with a weaker CPU and slower storage. The spawning time impact only applies when the app doesn't already have an app process and the OS will try to keep app processes cached in the background until memory pressure forces it to start killing them.

In the typical Zygote model, a template app process is created during boot and every app is spawned as a clone of it. This results in every app sharing the same initial memory content and layout, including sharing secrets that are meant to be randomized for each process. It saves time by reusing the initialization work. The initial memory usage is reduced due to copy-on-write semantics resulting in memory written only during initialization being shared between app processes.

The Zygote model weakens the security provided by features based on random secrets including Address Space Layout Randomization (ASLR), stack canaries, heap canaries, randomized heap layout and memory tags. It cripples these security features since every app has the values for every other app and the values don't change for fresh app processes until reboot. Much of the OS itself is implemented via non-user-facing apps with privileges reserved for OS components. The Zygote template is reused across user profiles, so it also provides a temporary set of device identifiers across profiles for each boot via the shared randomized values.

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.

LTE-only mode

If you have a reliable LTE connection from your carrier, you can reduce attack surface by disabling 2G / 3G connectivity in Settings ➔ Network & Internet ➔ Mobile network ➔ Preferred network type. Traditional voice calls will only work in the LTE-only mode if you have either an LTE connection and VoLTE (Voice over LTE) support or a Wi-Fi connection and VoWi-Fi (Voice over Wi-Fi) support. Currently, VoLTE / VoWi-Fi works on GrapheneOS but not on most carriers, since the configuration and extra apps for them on most carriers are not yet around.

This feature is not intended to improve the confidentiality of traditional calls and texts, but it might somewhat raise the bar for some forms of interception. It's not a substitute for end-to-end encrypted calls / texts or even transport layer encryption. LTE does provide basic network authentication / encryption, but it's for the network itself. The intention of the LTE-only feature is only hardening against remote exploitation by disabling an enormous amount of legacy code.