These are all fully supported production-ready targets supporting all the
- baseline security features and receiving full monthly security updates
- covering all firmware, kernel drivers, driver libraries / services and other
- device-specific code. A fully signed user build for these devices is a proper
- GrapheneOS release. Newer generation devices have stronger hardware / firmware
- security and hardware-based OS security features and are better development
- devices for that reason. It's not possible to work on everything via past
- generation devices. The best development devices are the Pixel 6 and 7 series.
-
-
-
SDK emulator target:
-
-
-
sdk_phone64_x86_64
-
-
-
These emulator targets don't receive full monthly security updates, don't
- provide all of the baseline security features and are intended for development
- usage.
-
-
We recommend using the sdk_phone64_x86_64 target in either the
- userdebug or eng variant for most development work.
-
-
Providing proper support for a device or generic device family requires
- providing an up-to-date kernel and device support code including driver
- libraries, firmware and device SELinux policy extensions. Other than some
- special cases like the emulator, the generic targets rely on the device support
- code present on the device. Shipping all of this is necessary for full security
- updates and is tied to enabling verified boot / attestation. Device-specific
- driver changes are required to support GrapheneOS features such as the
- hardware-level USB-C port control. There's also a lot of device-specific work to
- work around or resolve memory corruption bugs uncovered by our features. Most
- devices are also missing a lot of standard hardware-based security features we
- use such as hardware memory tagging so those features will inherently not be
- possible to port to a device not capable of it.
Arch Linux, Debian bookworm, Ubuntu 24.10 and Ubuntu 24.04 LTS are the
- officially supported operating systems for building GrapheneOS.
-
-
- Set up Debian GNU/Linux 12 (bookworm)
-
-
To build GrapheneOS, install the required packages:
-
-
apt install repo yarnpkg zip rsync
-
-
Your PATH may not contain directories like
- /sbin, and many system administration commands will fail. The
- adevtool from GrapheneOS requires the debugfs
- binary in /sbin. The simplest workaround is to add these
- directories to your PATH environment variable (and apply the
- change to your current shell):
Dependencies for fetching and verifying the sources:
-
-
-
repo
-
python3 (for repo)
-
git (both for repo and manual usage)
-
gnupg (for verifying AOSP releases and also used internally by repo for self-update verification)
-
openssh (for verifying GrapheneOS releases)
-
136GiB+ storage for a standard sync with history, 90GiB+ storage for a
- lightweight sync
-
-
-
Baseline build dependencies:
-
-
-
x86_64 Linux build environment
-
32GiB of memory or more. Link-Time Optimization (LTO) creates huge peaks
- during linking and is mandatory for Control Flow Integrity (CFI). Linking
- Vanadium (Chromium) and the Linux kernel with LTO + CFI are the most memory
- demanding tasks.
-
100GiB+ of additional free storage space for a typical build of the entire
- OS for a multiarch device
-
-
-
You can either obtain repo as a distribution package or the
- self-updating standalone version from the Android Open Source Project. The
- self-updating variant avoids dealing with out-of-date distribution packages and
- depends on GPG to verify updates.
-
-
The Android Open Source Project build system is designed to provide reliable and
- reproducible builds. To accomplish this, it provides a prebuilt toolchain and other
- utilities fulfilling most of the build dependency requirements itself. These prebuilt
- tools have reproducible builds themselves. It runs the build process within a loose
- sandbox to avoid accidental dependencies on the host system. The process of moving to
- a fully self-contained build process with minimal external dependencies is gradual and
- there are still dependencies that need to be installed on the host system.
-
-
Additional Android Open Source Project build dependencies not provided by the
- source tree:
-
-
-
diff (diffutils)
-
freetype2, fontconfig and any OpenType/TrueType font (such as DejaVu
- but anything works) for OpenJDK despite it being a headless variant
- without GUI support
-
hostname (inetutils) is used for detecting namespace support for build
- sandboxing
-
openssl
-
rsync
-
unzip
-
zip
-
-
-
Additional dependencies for extracting vendor files with adevtool:
-
-
-
Node.js 22 LTS
-
yarn
-
e2fsprogs (for the debugfs command used for extracting data from ext4 images)
-
-
-
Additional Vanadium (Chromium) build dependencies not provided by the source tree:
-
-
-
gperf
-
32-bit glibc
-
32-bit gcc runtime library
-
-
-
Additional dependencies for signing factory images releases:
Since this is syncing the sources for the entire operating system and application
- layer, it will use a lot of bandwidth and storage space.
-
-
You likely want to use the most recent stable tag, not the development branch, even
- for developing a feature. It's easier to port between stable tags that are known to
- work properly than dealing with a moving target.
The 15-qpr2 branch is the main development branch of
- GrapheneOS based on the latest release of Android 15 QPR2. It will follow
- along with the latest monthly and quarterly releases of Android 15 QPR2. The
- 15-qpr2 branch of GrapheneOS should be used for generic builds
- including the emulator, porting to other devices and for non-legacy
- officially supported devices.
-
-
The 15-qpr1-tegu branch is a device branch for the Pixel 9a
- based on the upstream Pixel 9a device branch which is still based on Android
- 15 QPR1 with security backports from after the main QPR1 development branch
- ended rather than Android 15 QPR2.
If your network is unreliable and repo sync fails, you can run the
- repo sync command again to continue from where it was interrupted. It
- handles connection failures robustly and you shouldn't start over from scratch.
Pick a specific release for a device from the releases page
- and download the source tree. Note that some devices use different Android Open Source
- Project branches so they can end up with different tags. Make sure to use the correct
- tag for a device. For devices without official support, use the latest tag marked as
- being appropriate for generic / other devices in the release notes.
The manifest for the latest stable release refers to the revisions in other
- repositories via commit hashes rather than tag names. This avoids the need to use a
- script to verify tag signatures across all the repositories, since they simply point
- to the same commits with the same hashes.
-
-
Note that the repo command itself takes care of updating itself and uses GPG to
- verify by default.
To update the source tree, run the repo init command again to select
- the branch or tag and then run repo sync -j8 again. You may need to add
- --force-sync if a repository switched from one source to another,
- such as when GrapheneOS forks an additional Android Open Source Project repository.
- You don't need to start over to switch between different branches or tags. You may
- need to run repo init again to continue down the same branch since
- GrapheneOS only provides a stable history via tags.
This section is specific to Pixel devices. The emulator and generic targets don't
- require extra vendor files.
-
-
Many of these components are already open source, but not everything is set up to
- be built by the Android Open Source Project build system. Switching to building these
- components from source will be an incremental effort. In many cases, the vendor files
- simply need to be ignored and AOSP will already provide them instead. Firmware cannot
- generally be built from source even when sources are available, other than to verify
- that the official builds match the sources, since it has signature verification (which
- is an important part of the verified boot and attestation security model).
-
-
The below commands need to only be run once to initially create a working
- environment. (Note: On Debian, yarn is reserved for a binary in
- cmdtest; use yarnpkg instead.)
The build has to be done from bash or zsh as envsetup.sh is not compatible with other
- shells.
-
-
Set up the build environment:
-
-
source build/envsetup.sh
-
-
Select the desired build target (husky is the Pixel 8 Pro):
-
-
lunch husky-cur-user
-
-
For past stable tags and legacy branches, don't pass the Android release:
-
-
lunch husky-user
-
-
For a development build, you may want to replace user with
- userdebug in order to have better debugging support. Production builds
- should be user builds as they are significantly more secure and don't
- make additional performance sacrifices to improve debugging.
-
-
Set OFFICIAL_BUILD=true to include the Updater app. You
- must change the URL in
- packages/apps/Updater/res/values/config.xml to your own update server
- URL. Using the official update server with a build signed with different keys will not
- work and will essentially perform a denial of service attack on our update service. If
- you try to use the official URL, the app will download an official update and will
- detect it as corrupted or tampered. It will delete the update and try to download it
- over and over again since it will never be signed with your key.
To reproduce a past build, you need to export BUILD_DATETIME and
- BUILD_NUMBER to the values set for the past build. These can be obtained
- from out/build_date.txt and out/build_number.txt in a build
- output directory and the ro.build.date.utc and
- ro.build.version.incremental properties which are also included in the
- over-the-air zip metadata rather than just the OS itself.
-
-
The signing process for release builds is done after completing builds and replaces
- the dm-verity trees, apk signatures, etc. and can only be reproduced with access to
- the same private keys. If you want to compare to production builds signed with
- different keys you need to stick to comparing everything other than the
- signatures.
-
-
Additionally, set OFFICIAL_BUILD=true per the instructions above to
- reproduce the official builds. Note that if you do not change the URL to your own
- domain, you must disable the Updater app before connecting the device
- to the internet, or you will be performing a denial of service attack on our official
- update server.
Incremental builds (i.e. starting from the old build) usually work for development
- and are the normal way to develop changes. However, there are cases where changes are
- not properly picked up by the build system. For production builds, you should remove
- the remnants of any past builds before starting, particularly if there were
- non-trivial changes:
-
-
rm -r out
-
-
Next, start the build process with the m command:
-
-
m target-files-package
-
-
For the Pixel 6, Pixel 6 Pro and Pixel 6a you currently need m
- vendorbootimage target-files-package instead of
- target-files-package.
-
-
For the Pixel 7, Pixel 7 Pro, Pixel 7a, Pixel Tablet, Pixel Fold, Pixel 8,
- Pixel 8 Pro, Pixel 8a, Pixel 9, Pixel 9 Pro, Pixel 9 Pro XL and Pixel 9 Pro Fold
- you currently need m vendorbootimage vendorkernelbootimage
- target-files-package instead of target-files-package.
-
-
The -j parameter can be passed to m to set a specific
- number of jobs such as -j4 to use 4 jobs. By default, the build system
- sets the number of jobs to NumCPU() + 2 where NumCPU() is the
- number of available logical CPUs.
-
-
For an emulator build, always use the development build approach below.
The normal production build process involves building a target files package to be
- resigned with secure release keys and then converted into factory images and/or an
- update zip via the sections below. If you have a dedicated development device with no
- security requirements, you can save time by using the default build target rather than
- target-files-package. Leave the bootloader unlocked and flashing the raw images that
- are signed with the default public test keys.
-
-
To build the default build target:
-
-
m
-
-
Technically, you could generate test key signed update packages. However, there's
- no point of sideloading update packages when the bootloader is unlocked and there's no
- value in a locked bootloader without signing the build using release keys, since
- verified boot will be meaningless and the keys used to verify sideloaded updates are
- also public. The only reason to use update packages or a locked bootloader without
- signing the build with release keys would be testing that functionality and it makes a
- lot more sense to test it with proper signing keys rather than the default public test
- keys.
Keys need to be generated for resigning completed builds from the publicly
- available test keys. The keys must then be reused for subsequent builds and cannot be
- changed without flashing the generated factory images again which will perform a
- factory reset. Note that the keys are used for a lot more than simply verifying
- updates and verified boot.
-
-
The sample certificate subject (CN=GrapheneOS) should be replaced with
- your own information.
-
-
You should set a passphrase for the signing keys to keep them at rest until you
- need to sign a release with them. The GrapheneOS scripts (make_key and
- encrypt-keys) encrypt the signing keys using scrypt for key derivation
- and AES256 as the cipher. If you use swap, make sure it's encrypted, ideally with an
- ephemeral key rather a persistent key to support hibernation. Even with an ephemeral
- key, swap will reduce the security gained from encrypting the keys since it breaks the
- guarantee that they become at rest as soon as the signing process is finished.
- Consider disabling swap, at least during the signing process.
-
-
The encryption passphrase for all the keys generated for a device needs to
- match for compatibility with the GrapheneOS scripts.
-
-
To generate keys for raven (you should use unique keys per device
- variant):
You can (re-)encrypt your signing keys using the encrypt-keys script,
- which will prompt for the old passphrase (if any) and new passphrase:
-
-
script/encrypt-keys keys/raven
-
-
The script/decrypt-keys script can be used to remove encryption,
- which is not recommended. The script exists primarily for internal usage to decrypt
- the keys in tmpfs to perform signing.
GrapheneOS currently doesn't use out-of-band updates to APEX
- components, so these are all signed with the OS releasekey and verified
- boot key to avoid needing many extra pairs of keys. Each APEX needs an APK
- signing key and verified boot signing key. If you want to ship out-of-band
- updates to APEX components, you'll need to deal with this and you should
- make a separate pair of keys for each one.
-
-
Consult the upstream documentation on generating these keys. It will
- likely be covered here in the future, especially if non-flattened APEX
- components become unavoidable.
Build and package up the tools needed to generate over-the-air update packages:
-
-
m otatools-package
-
-
Copy build artifacts to releases directory:
-
-
script/finalize.sh
-
-
Generate a signed release build with the generate-release.sh script:
-
-
script/generate-release.sh raven BUILD_NUMBER
-
-
The factory images and update package will be in
- releases/BUILD_NUMBER/release-raven-BUILD_NUMBER.
- The update zip performs a full OS installation so it can be used to update from
- any previous version. More efficient incremental updates are used for official
- over-the-air GrapheneOS updates and can be generated by keeping around past
- signed target_files zips and generating incremental updates from
- those to the most recent signed target_files zip.
Running script/generate-release.sh also generates channel
- metadata for the update server. If you configured the Updater client URL and set
- the build to include it (see the information on OFFICIAL_BUILD
- above), you can push signed over-the-air updates via the update system. Simply
- upload the update package to the update server along with the channel metadata
- for the release channel, and it will be pushed out to the update client. The
- DEVICE-beta and DEVICE-stable
- metadata provide the Beta and Stable release channels used by the update client.
- The DEVICE-testing metadata provides an internal testing
- channel for the OS developers, which can be temporarily enabled using adb
- shell setprop sys.update.channel testing. The name is arbitrary and you
- can also use any other name for internal testing channels.
-
-
For GrapheneOS itself, the testing channel is used to push out updates to developer
- devices, followed by a sample future release to test that the release which is about
- to be pushed out to the Beta channel is able to update to a future release. Once it's
- tested internally, the release is pushed out to the Beta channel, and finally to the
- Stable channel after public testing. A similar approach is recommended for derivatives
- of GrapheneOS.
Incremental updates shipping only the changes between two versions can be generated
- as a much more efficient way of shipping updates than a full update package containing
- the entire operating system. The GrapheneOS Updater app will automatically use a delta
- update if one exists for going directly from the currently installed version to the
- latest release. In order to generate a delta update, the original signed target files
- package for both the source version and target version are needed. The
- script/generate-delta.sh script provides a wrapper script for generating
- delta updates by passing the device, source version build number and target version
- build number. For example:
Incremental updates are uploaded alongside the update packages and update metadata
- on the static web server used as an update server. The update client will
- automatically check for an incremental update and use it if available. No additional
- metadata is needed to make incremental updates work.
Like the Android Open Source Project, GrapheneOS contains some code that's built
- separately and then bundled into the source tree as binaries. This section will be
- gradually expanded to cover building all of it.
The Linux kernel is built separately using an AOSP kernel build system
- wrapping the upstream Linux kernel build system. Since it's a separate build
- system from the rest of the OS, the kernels are built separately. Many of the
- repositories are shared with the rest of the OS including the repositories
- providing the prebuilt toolchain for reproducible builds not depending on the
- tools from the host OS.
-
-
Additional Linux kernel build dependencies for 4th and 5th generation
- Pixels not provided by the source tree:
The default kernel version for the emulator is 6.6. You can change the
- kernel version used for the x86_64 emulator target supported by GrapheneOS in
- device/generic/goldfish/board/kernel/x86_64.mk.
tools/bazel run //common:kernel_aarch64_microdroid_dist --config=stamp --lto=full
-
-
Replace the prebuilt kernel image in the OS source tree at
- packages/modules/Virtualization/microdroid/kernel/android15-6.6/arm64/kernel-6.6 with your image
- out/kernel_aarch64_microdroid/dist/Image.
-
-
To build the x86_64 kernel image for microdroid:
-
-
tools/bazel run //common:kernel_x86_64_microdroid_dist --config=stamp --lto=full
-
-
Replace the prebuilt kernel image in the OS source tree at
- packages/modules/Virtualization/microdroid/kernel/android15-6.6/x86_64/kernel-6.6 with your image
- out/kernel_x86_64_microdroid/dist/bzImage.
Vanadium is a hardened fork of Chromium developed by GrapheneOS and used to provide
- the WebView and optionally the standalone browser app. It tracks the Chromium
- release cycles along with having additional updates for downstream changes to the
- privacy and security hardening patches, so it's updated at a different schedule than
- the monthly Android releases.
-
-
The browser and the WebView are independent applications built from the Chromium
- source tree. The GrapheneOS browser build is located at external/vanadium and the
- WebView is at external/chromium-webview.
You will be prompted to enter a password which will be requested by the
- generate-release.sh script for signing releases. You should back up
- the generated keystore with your other keys.
-
-
Fetch the Chromium sources:
-
-
fetch --nohooks android
-
-
Sync to the latest stable release for Android (replace VERSION with
- the correct value):
-
-
cd src
-git fetch --tags
-git checkout VERSION
-
-
Apply the GrapheneOS patches on top of the tagged release:
-
-
git am --whitespace=nowarn --keep-non-patch ../patches/*.patch
Copy the GrapheneOS configuration from ../args.gn and save/exit the
- editor. Modify target_cpu as needed if the target is not arm64. For
- x86_64, the correct value for target_cpu is x64, but note
- that the Android source tree refers to it as x86_64.
-
-
You need to set trichrome_certdigest to the correct value for your
- generated signing key. You can obtain this with the following command:
The apks need to be copied from out/Default/apks/release/*.apk
- into the Android source tree at
- external/vanadium/prebuilt/arm64/ with arm64
- substituted with the correct value for other architectures (arm, x86, x86_64).
-
-
WebView provider apps need to be whitelisted in
- frameworks/base/core/res/res/xml/config_webview_packages.xml. By default,
- only the Vanadium WebView is whitelisted.
The official releases of our App Store, Auditor, Camera and PdfViewer apps are
- bundled as apks into external/ repositories. The no-code AppCompatConfig and
- GmsCompatConfig apps are done the same way. These are built and signed with the
- standard gradle Android plugin build system.
-
-
The TalkBack screen reader is built from our talkback fork repository and
- included as a prebuilt signed with the OS releasekey. It may be presigned in
- the future similar to our standalone apps if we decide to do out-of-band
- releases.
GrapheneOS uses a static web server as the update server. The release signing
- script generates the necessary metadata alongside the release files. You simply need
- to host these files at the URL configured in
- packages/apps/Updater/res/values/config.xml. See above for details on
- including the Updater app in a release. These are the relevant files:
Generally, you should start by uploading the ota_update, factory images and testing
- channel metadata.
-
-
The testing release channel is an example of an internal release
- channel not configurable via the update client GUI. Internal release channels can have
- arbitrary names. You can override the release channel configured in the update client
- via ADB with the following command:
-
-
adb shell setprop sys.update.channel CHANNEL_NAME
-
-
Replace CHANNEL_NAME with the name of the release channel, such as
- testing.
-
-
After pushing out and testing the new release via the internal release channel,
- it's recommended to build a sample future release and push that out as another update
- via an internal testing channel. This is important to test that the changes in your
- latest release have not broken the future upgrade path.
-
-
Finally, once the release has gone through internal testing, upload the metadata
- for the beta channel. Once the release has gone through beta testing, upload the
- metadata for the stable channel.
-
-
Delta update packages should simply be uploaded alongside the rest of the releases.
- The update client will check for the presence of a delta update from the current
- version on the device to the newer release in the selected release channel. There is
- no additional metadata to include alongside the delta update package.
Manifests for stable releases are generated with repo manifest -r
- after tagging the release across all the repositories in a temporary branch and
- syncing to it. This provides a manifest referencing the commits by hashes instead of
- just tags to lock in the revisions. This makes verification of the releases simpler,
- since only the manifest tag needs to be verified rather than tags for each
- repository. This also means the whole release can be verified using the GrapheneOS
- signing key despite referencing many upstream repositories that are not forked by the
- GrapheneOS project.
It can be useful to set up a standalone installation of the SDK separate from
- the Android Open Source Project tree. This is how the prebuilt apps are built, rather
- than using the older branch of the SDK in the OS source tree.
-
-
Android Studio can also be set up to use an existing SDK and will recognize it and use
- it automatically if Android Studio is installed with an SDK installation already
- available and set up in the environment. You'll also likely want a working
- command-line SDK environment even if you do heavily use Android Studio.
-
-
Using the official releases of the SDK is recommended for simplicity, although with
- a lot of effort you can build everything yourself. Distribution packages are generally
- quite out-of-date and should be avoided. To set up a minimal SDK installation at
- ~/android/sdk without Android Studio:
Set ANDROID_HOME to point at the SDK installation in your current
- shell and shell profile configuration. You also need to add the
- cmdline-tools binaries to your PATH. For example:
You can install Android Studio alongside the standalone SDK and it will detect it
- via the ANDROID_HOME environment variable rather than installing another
- copy of it. For example:
-
-
cd ~/android
-curl -O https://dl.google.com/dl/android/studio/ide-zips/2024.3.2.15/android-studio-2024.3.2.15-linux.tar.gz
-echo '2fcb3c975fd0e002441af7734cb2eef6c459964372443310bcaf26a195ce7881 android-studio-2024.3.2.15-linux.tar.gz' | sha256sum -c
-tar xvf android-studio-2024.3.2.15-linux.tar.gz
-rm android-studio-2024.3.2.15-linux.tar.gz
-mv android-studio studio
Use the Gradle wrapper script to update Gradle to the latest version. You should run this twice rather than only once to upgrade the Gradle wrapper with the new Gradle version. For example, with Gradle 8.10.2:
This section will be expanded to cover various test suites and testing procedures
- rather than only the current very minimal coverage of the Compatibility Test Suite
- (CTS).
To test a build for the emulator, run emulator within the build
- environment. The emulator will use CPU hardware acceleration via KVM along with
- optional graphics acceleration via the host GPU if these are available. The
- emulator does not work on Wayland due to the AOSP provided Qt build missing the
- Wayland platform plugin.
Testing with the Compatibility Test Suite (CTS) can be done by either building the
- test suite from source or using the official releases.
-
Official releases of the CTS can be downloaded from
- the Compatibility
- Suite Downloads page. You should download the CTS for the relevant release
- (Android 12) and architecture (ARM). There's a separate zip for the main CTS, the
- manual portion (CTS Verifier) and the CTS for Instant Apps. The latest release of the
- CTS Media Files also needs to be downloaded from that section.
You'll need a device attached to your computer with ADB enabled along with the
- Android SDK installed. The build-tools and platform-tools packages need to be
- installed and the binaries need to be added to your PATH. See the
- standalone SDK installation instructions above.
-
-
Copy media onto the device:
-
cd android-cts-media-1.5
-./copy_images.sh
-./copy_media.sh
-
-
You also need to do some basic setup for the device. It's possible for changes from
- a baseline install to cause interference, so it can be a good idea to factory reset
- the device if assorted changes have been made. The device needs to be running a user
- build for the security model to be fully intact in order to pass all the security
- tests. A userdebug build is expected to fail some of the tests. GrapheneOS also makes
- various changes intentionally deviating from the requirements expected by the CTS, so
- there will always be some expected failures. A few of the tests are also known to be
- quite flaky or broken even with the stock OS and/or AOSP. These will be documented
- here at some point.
-
-
-
Must be connected to a WiFi network with IPv6 internet access
-
Must have a working SIM card with mobile data with IPv6 internet access
-
Disable SIM lock
-
Enable Bluetooth
-
Enable NFC
-
Open / close Chromium to deal with initial setup
-
Prop up with a good object to focus on and good lighting for Camera tests.
- Both the front and rear cameras will be used, so ensure this is true for both the
- front and the rear cameras.
-
Bluetooth beacons for Bluetooth tests
-
Must have a great GPS/GNSS signal for location tests
-
SIM card with carrier privilege rules
-
Secure element applet installed on the embedded secure element or SIM
- card
-
At least one Wi-Fi RTT access point powered up but not connected to any
- network
Note that _JAVA_OPTIONS being set will break the version detection.
-
To obtain a list of CTS modules:
-
list modules
-
To run a specific module and avoid wasting time capturing device information:
-
run cts --skip-device-info --module CTS_MODULE_NAME
-
To speed up initialization after running some initial tests:
-
run cts --skip-device-info --skip-preconditions --module CTS_MODULE_NAME
-
It's possible to run the whole standard CTS plan with a single command, but running
- specific modules is recommended, especially if you don't have everything set up for
- the entire test suite.
The Android Open Source Project has branches and/or tags for the releases of many
- different components. There are tags and/or branches for the OS, device kernels,
- mainline components (APEX), the NDK, Android Studio, the platform-tools distribution
- packages, the CTS, androidx components, etc. You should obtain the sources via
- manifests using the repo tool, either using the manifest for a tag / branch in
- platform/manifest.git or a manifest provided elsewhere. Different projects use
- different subsets of the repositories. Many of the repositories only exist as an
- archive for older releases and aren't referenced in current manifests.
-
-
Some components don't have the infrastructure set up to generate and push their own
- branches and tags to AOSP. In other cases, it's simply not obvious to an outsider
- which one should be used. As long as the component is built on the standard Android
- project CI infrastructure, it's possible to obtain the manifests to build it based on
- the build number, which is generally incorporated into the build. For example, even
- without a platform-tools tag, you can obtain the build number from adb
- version or fastboot version. Their version output uses the format
- VERSION-BUILD_NUMBER such as 30.0.3-6597393 for the
- version 30.0.3 where the official release had the build number
- 6597393. You can obtain the manifest properties with the appropriate
- repository revisions from ci.android.com with a URL like this:
-
- https://ci.android.com/builds/submitted/6597393/sdk/latest/view/repo.prop
-
-
The platform-tools tags exist because the GrapheneOS project requested them. The
- same could be done for other projects, but it's not strictly necessarily as long as
- it's possible to obtain the build number to request the information from the Android
- project CI server.
-
-
As another kind of example, prebuilts/clang,
- prebuilts/build-tools, etc. have a manifest file committed alongside the
- prebuilts. Other AOSP toolchain prebuilts reference a build number.
The following programming languages are acceptable for completely
- new GrapheneOS projects:
-
-
Kotlin for apps and any services closely tied to the apps, now that it's not
- only officially supported by the Android SDK and Android Studio but also the
- default language with Kotlin exclusive enhancements to the APIs
-
Web applications must be entirely static HTML/CSS/JavaScript. TypeScript would
- make sense at a larger scale but there are no plans for any large web
- applications.
-
Rust with no_std for low-level code used in a hypervisor, kernel,
- daemon, system library, etc. Keep in mind that low-level code is to be avoided
- whenever a higher-level language is better suited to the job. In general,
- the project aims to avoid creating more low-level code manually dealing with
- memory ownership and lifetimes in the first place.
-
C in rare cases for very small and particularly low-level projects without
- opportunities to reduce the trusted computing base for memory corruption to
- any significant degree with Rust, such as for the hardened_malloc project
-
arm64 assembly in extremely rare cases where C or Rust aren't usable with
- compiler intrinsics
-
Python 3 for small (less than 500 lines) development-related scripts that are
- not exposed to untrusted input. It's never acceptable to use it for
- client-side code on devices or for servers. It isn't used on the servers even
- for non-application-server code.
-
Bash for tiny (less than 200 lines) build scripts without any non-trivial
- logic where Python would be an annoyance.
-
-
-
Much of the work is done on existing projects, and the existing languages should be
- used unless there are already clear stable API boundaries where a different language
- could be used without causing a substantial maintenance burden. The following
- languages are typical from most to least common: Java, C++, C, JavaScript, arm64
- assembly, POSIX shell, Bash.
For existing projects, use the official upstream code style. Avoid using legacy
- conventions that they're moving away from themselves. Follow the code style they use
- for new additions. Some projects have different code styles for different directories
- or files depending on their sources, in which case respect the per-file style.
-
-
For new projects, follow the official code style for the language. Treat the
- standard library APIs as defining the naming style for usage of the language, i.e. C
- uses variable_or_function_name, type_name,
- MACRO_NAME while JavaScript uses variable_or_function_name,
- ClassName and CONSTANT_NAME. For Python, follow PEP8 and the
- same goes for other languages with official styles whether defined in a document or by
- the default mode for the official formatting tool like rustfmt.
-
-
For cases where there isn't an official or prevailing code style for other things,
- avoid tabs, use 4-space indents, function_name,
- variable_name, TypeName and CONSTANT_NAME.
- Prefer single-line comment syntax other than rare cases where it makes sense to add a
- tiny comment within a line of code. In languages with the optional braces misfeature
- (C, C++, Java), always use them. Open braces on the same line as function definitions
- / statements. Wrap lines at 100 columns except in rare cases where it would be far
- uglier to wrap the line.
-
-
For JavaScript, all code should be contained within ES6 modules. This means every
- script element should use type="module". Modules provide proper
- namespacing with explicit imports and exports. Modules automatically use strict mode,
- so "use strict"; is no longer needed. By default, modules are also
- deferred until after the DOM is ready, i.e. they have an implicit defer
- attribute. This should be relied upon rather than unnecessarily listening for an event
- to determine if the DOM is ready for use. It can make sense to use async
- to run the code earlier if the JavaScript is essential to the content and benefits
- from being able to start tasks before the DOM is ready, such as retrieving important
- content or checking if there's a login session. Always end lines with semicolons
- (since automatic insertion is poorly designed) and always use const to
- declare variables, unless they are reassigned in which case they should be declared
- with let but never use var as it is effectively broken. Try
- to prefer loops with for..of. JavaScript must pass verification with
- eslint using the following eslint.config.js configuration:
Cookies are only used for login sessions. Every cookie must have the
- __Host prefix to guarantee that it has the Secure
- attribute and Path=/. The HttpOnly and
- SameSite=Strict flags should also always be included. These kinds
- of cookies can provide secure login sessions in browsers with fully working
- SameSite=Strict support.
-
-
CSRF mitigation should be implemented via enforcing the presence of
- Sec-Fetch-Site with the value same-origin. Services using only POST can also do
- this via the more backwards compatible Origin header.
-
-
For web content, use dashes as user-facing word separators rather than underscores.
- Page titles should follow the scheme "Page | Directory | Higher-level directory |
- Site" for usability with a traditional title as the Open Graph title.
-
-
HTML must pass verification with validatornu and xmllint.
- Ensuring that it parses as XML with xmllint catches many common mistakes
- and typos that are missed by HTML validation due to the ridiculously permissive nature
- of HTML. This enforces closing every tag, using proper escaping and so on. XHTML does
- not really exist anymore and we simply use XML parsing as an enforced coding standard
- and lint pass. It can also be useful to make it compatible with XML-based tooling.
-
-
Avoid designing around class inheritance unless it's a rare case where it's an
- extremely good fit or the language sucks (Java) and it's the least bad approach, but
- still try to avoid it.
-
-
Use concise but self-explanatory variable names. Prefer communicating information
- via naming rather than using comments whenever possible. Don't name variables
- i, j, k, etc. like C programmers. It's okay to
- use things like x and y for parameters if the function is
- genuinely that generic and operates on arbitrary values. In general, try to scope
- variables into the most limited scope (in C or C++, be careful about this when
- references are taken).
-
-
Write code that's clean and self-explanatory. Use comments to explain or justify
- non-obvious things, but try to avoid needing them in the first place. In most cases,
- they should just be communicating non-local information such as explaining why an
- invariant is true based on the code elsewhere (consider a runtime check to make sure
- it's true, or an assertion if performance would be an issue). Docstrings at the top of
- top-level functions, modules, etc. are a different story and shouldn't be avoided.
Make extensive usage of well designed standard library modules. For apps, treat
- Jetpack (androidx) as part of the standard library and make good use of it. For Java,
- Guava can also be treated as part of the standard library.
-
-
Libraries outside of the standard library should be used very cautiously. They
- should be well maintained, stable, well tested and widely used. Libraries implemented
- with memory unsafe languages should generally be avoided (one exception: SQLite).
-
-
Generally, frameworks and libraries existing solely to provide different paradigms
- and coding patterns are to be avoided. They increase barrier to entry for developers,
- generally only increase complexity unless used at very large scales (and may not even
- make things simpler in those cases) and come and go as fads. This is only okay when
- it's part of the standard libraries or libraries that are considered standard
- (androidx, Guava) by GrapheneOS and should still be approached cautiously. Only use it
- if it truly makes the correct approach simpler. Ignore fads and figure out if it
- actually makes sense to use, otherwise just stick to the old fashioned way if the
- fancy alternatives aren't genuinely better.
By default, GrapheneOS uses gesture-based navigation. We recommend reading our
- guide on gesture navigation and giving it a chance even if you think you won't
- like it. Our experience is that when armed with the appropriate knowledge, the
- vast majority of users prefer the newer gesture navigation approach.
-
-
The system navigation mode can be configured in Settings > System >
- Gestures > Navigation
- mode. The same menu is also available in Settings >
- Accessibility > System
- controls > Navigation mode.
The bottom of the screen is a reserved touch zone for system navigation. A
- line is displayed in the center to show that the navigation bar is present
- across the entire bottom of the screen. In most apps, this area will display
- padding. Modern apps are able to tell the OS that they can handle not having
- the padding to display app content there while still not being able to receive
- touches from it. Open up the Settings app for an example.
-
-
Swiping up from the navigation bar while removing your finger from the
- screen is the Home gesture.
-
-
Swiping up from the navigation bar while holding your finger on the screen
- before releasing is the Recent Apps gesture. The most
- recently opened activity is always on the furthest right. Each step left goes
- one step back through the history of recently opened apps. Opening an app with
- the recent apps activity will place it on the furthest right in the recent
- apps order just like a new app being opened.
-
-
The recent apps activity has a screenshot button as an alternative to
- holding power and volume down while using an app.
-
-
Rather than opening the recent apps activity, you can swipe left on the
- navigation bar for the Previous app and swipe right for the
- Next app. This will not change the recent apps order. This is
- usually the best way to navigate through recent apps.
-
-
Swiping from either the left or the right of the screen within the app (not
- the navigation bar) is the Back gesture. Apps are supposed to
- avoid implementing conflicting gestures, but have the option to override this
- gesture if they truly need to get rid of it. Some legacy apps without active
- development of their UI still haven't addressed this despite gestures being
- the default for several years on Google Android. You can avoid triggering the
- back gesture in one of 2 easy ways: avoid swiping from right near the edge or
- hold your finger on the side of the screen for a moment before swiping. The
- more advanced option is using a diagonal swipe pointing sharply to the bottom
- of the screen since this will bypass the back gesture but will still trigger
- most app gestures. The advanced option is the most convenient approach once
- you get used to doing it.
-
-
The launcher uses a swipe up gesture starting anywhere on the screen to
- open the app drawer from the home screen. You need to start that gesture above
- the system navigation bar since any gesture starting on the navigation bar is
- handled by the OS as a system navigation gesture.
3-button navigation is Android's oldest touchscreen-based navigation
- system. It will remain supported for the foreseeable future to provide
- accessibility for users unable to easily use the gestures. It's older than
- 2-button navigation but isn't considered a legacy feature.
-
-
A large row across the bottom of the screen is reserved for navigation
- buttons. The Back button is on the left, the
- Home button is in the center and the Recent
- Apps button is on the right.
-
-
In the recent apps activity, the most recently opened activity is always on
- the furthest right. Each step left goes one step back through the history of
- recently opened apps. Opening an app with the recent apps activity will place
- it on the furthest right in the recent apps order just like a new app being
- opened.
-
-
The recent apps activity has a screenshot button as an alternative to
- holding power and volume down while using an app.
GrapheneOS inherits the same baseline approach to storage access as modern
- Android and extends it with our Storage Scopes feature as a fully compatible
- alternative to standard Android storage permissions. This section provides an
- overview of the standard approach to storage access primarily to provide context
- for explaining Storage Scopes.
-
-
There are two types of app-accessible storage:
-
-
-
app-private ("internal") storage:
-
-
inaccessible to other apps
-
doesn't require any permission for full access
-
cleared when the app is uninstalled
-
-
-
shared ("external") storage:
-
-
shared with other apps
-
access is regulated with permissions
-
files persist after uninstallation
-
- Android/data/ and Android/obb/ directories aren't considered to be parts
- of shared storage.
-
-
-
-
For modern apps, access to the shared storage is controlled in the following way:
-
-
-
Without any storage permission, an app is allowed to:
-
-
create media files in standard directories (audio in Music/,
- Ringtones/, etc, images in Pictures/ and DCIM/, videos in DCIM/
- and Movies/)
-
create files of any type (both media and non-media) in Documents/
- and Download/
-
create new directories inside standard directories
-
rename/delete files that were created by the app itself
-
rename/delete directories if it can rename/delete all files within
- those directories
-
-
-
Media access permission ("Allow access to media only",
- READ_EXTERNAL_STORAGE) allows the app to read media files
- that were created by other apps. Non-media files remain invisible to it.
- For apps targeting Android 13, the media access permission is split into
- READ_MEDIA_IMAGES, READ_MEDIA_VIDEO and
- READ_MEDIA_AUDIO.
-
Media management special access permission ("Allow app to manage media",
- MANAGE_MEDIA) allows the app to delete and to rename media
- files created by other apps.
-
"All files access" special access permission (MANAGE_EXTERNAL_STORAGE)
- allows the app to read, create, rename and delete files and directories
- of any type in any directory of the shared storage (including the root
- directory).
-
-
-
For legacy apps (those that target Android 9 or lower and those that target
- Android 10 and request legacy storage mode), storage access permissions have
- a different meaning:
-
-
Without a storage permission, app is not allowed any type of access to
- any files or directories inside the shared storage.
-
READ_EXTERNAL_STORAGE permission allows the app to read both
- media and non-media files in any directory.
-
WRITE_EXTERNAL_STORAGE permission allows the app to create,
- rename and delete files (of any type) and directories in any directory of
- shared storage (including the root directory).
-
-
-
Additionally, both modern and legacy Android apps can open the system file
- picker interface to have the user store or load one or more files/directories on
- their behalf. This type of access doesn't require any of the permissions listed
- above. Using this approach gives the user control over where files are stored in
- their home directory and which files/directories can be used by the app. This is
- based on the Storage Access Framework (SAF) introduced in Android 4.4. SAF allows
- the user to grant access to files/directories in their home directory, external
- drives and also app-based storage providers such as network shares, cloud storage,
- an encrypted volume, an external drive with a filesystem the OS doesn't support
- for external drives, etc. This is the only way to use those app-based storage
- providers and modern Android has removed the legacy approach for accessing
- external drives.
GrapheneOS provides the Storage Scopes feature as a fully compatible alternative
- to the standard Android storage permissions.
- Storage Scopes can be enabled only if the app doesn't have any storage permission.
- Enabling Storage Scopes makes the app assume that it has all of storage permissions
- that were requested by it, despite not actually having any of them.
-
-
This means that the app can't see any of the files that were created by other apps.
- The app is still allowed to create files and directories, same as any other modern
- app that doesn't have any storage access permission.
-
-
Apps that would normally use the legacy storage mode are switched to the
- modern storage mode when Storage Scopes is enabled.
-
-
If the app requests the "All files access" permission (or is a legacy app
- that requests WRITE_EXTERNAL_STORAGE permission), then the write
- restrictions that are normally applied to apps that don't have a storage access
- permission are relaxed to provide the same write access that the app would have if
- it was granted the "All files access" permission.
- This is done to ensure compatibility with apps that, for example, create a new
- directory in the root of shared storage, or write a text file (eg lyrics.txt) to
- the Music/ directory (normally, only audio files can be placed there).
- No additional read access is granted to such apps, they still can see only their
- own files.
-
-
-
For all other apps, enabling Storage Scopes doesn't grant any additional
- storage access beyond what a modern app that doesn't have any storage permission
- already has.
-
-
Optionally, users can specify which of the files created by other apps the app
- can access. Access can be granted to a specific file or to all files in
- a directory. The standard SAF picker is used for this purpose in a special mode
- where it shows only shared storage files/directories.
-
-
The most significant limitation of Storage Scopes is the fact that the app
- will lose access to files that it created if it's uninstalled and then installed
- again, same as any other app that doesn't have a storage access permission.
- As a workaround, users can manually grant access to these files/directories via
- SAF picker.
On Android, contact access is controlled with an all-or-nothing Contacts permission, which grants
- both read and write access to all contacts stored on the device.
-
-
A lot of apps (e.g. popular messaging apps) refuse to work unless the Contacts permission is granted.
-
-
GrapheneOS provides the Contact Scopes feature as an alternative to granting the Contacts permission.
- Enabling Contact Scopes makes the app assume that it has the Contacts permission, despite not actually
- having it. By default, an app that has Contact Scopes enabled is not allowed any kind of contact access.
-
-
Optionally, read access can be granted to the following scopes:
-
-
-
Contact data (phone number or email). Access to each type of number and email in a contact is
- granted separately. Access to the contact name is granted automatically.
-
Single contact. Access is granted to all contact data, except contact photo.
-
Contact group ("label"). Equivalent to granting access to all contacts in the group. Any contact
- can be in any number of contact groups.
-
-
-
The type and name of the account that the contact is stored in are fully hidden from the app. The name
- of the contact account is usually the same as the email address of that account.
-
-
When Contact Scopes is enabled, write access is fully blocked: the app is not allowed to edit any
- contact data, add or remove contacts, etc.
GrapheneOS includes all of the accessibility features from the Android Open
- Source Project and strives to fill in the gaps from not including Google apps and
- services. We include our own fork of the open source TalkBack accessibility
- service along with a Monochromacy option for the standard color correction
- menu.
-
-
GrapheneOS does not yet include a text-to-speech (TTS) service in the base OS
- due to limitations of the available options. Including one is planned in the
- future when a suitable option is available. RHVoice and eSpeak NG are both open
- source and are the most common choices by GrapheneOS users. Both of these work
- fine but have licensing issues. eSpeak NG has added Direct Boot based on our
- request for it, meaning it is able to function before the first unlock. RHVoice is
- missing Direct Boot and can't run before the first unlock. Installing and setting
- up either one of these or another TTS app will get TalkBack working. TalkBack
- itself supports Direct Boot and works before the first unlock but it needs to have
- a TTS app supporting it in order to do more than playing the activation sound
- before the first unlock. After installing a TTS service, you need to select it in
- the OS configuration to accept activating it. The OS will display one of them as
- already selected, but it won't simply work from being installed as that wouldn't
- be safe. This is the same as the stock OS but it comes with one set up
- already.
-
-
GrapheneOS disables showing the characters as passwords are typed by default. You
- can enable this in Settings >
- Security & privacy > Privacy > Show passwords.
-
-
Third party accessibility services can be installed and activated. This
- includes the ones made by Google. Most of these will work but some may have a hard
- dependency on functionality from Google Play services for some of their
- functionality or to run at all. Accessibility services are very powerful and we
- strongly recommend against using third party implementations if you can get by
- well without them. We plan to add safeguards in this area while still keeping them
- working without problematic barriers.
The update system implements automatic background updates. It checks for updates
- approximately once every six 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.
The settings are available in the Settings app in System > System update.
-
-
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.
-
-
The "Require device to be charging" setting controls whether updates will
- only be performed when the device is charging.
-
-
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.
-
-
The "Notification settings" option is a shortcut to the System Updater notification
- settings which allows you to control notification settings from System Updater such as
- notification dot, lock screen, and noisy / silent notifications. These notifications
- include updater errors, progress, already up to date, and reboot prompts. By default all
- notifications are enabled.
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
- over-the-air updates (Updater app) and sideloaded updates (recovery).
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 System Updater and disabling the app. If you do
- this, you'll need to remember to enable it again to start receiving updates.
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
- 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 interface.
-
-
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 raven-ota_update-2021122018.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.
Our USB-C port and pogo pins setting protects against attacks through
- USB-C or pogo pins while the OS is booted. For the majority of devices without pogo
- pins, the setting is labelled USB-C port.
-
-
The setting is available in Settings >
- Security > Exploit protection.
-
-
The setting has five modes:
-
-
-
Off
-
Charging-only
-
Charging-only when locked
-
Charging-only when locked, except before first unlock
-
On
-
-
-
The default is Charging-only when locked, which significantly reduces
- attack surface when the device is locked. After locking, it blocks any new USB
- connections immediately and disables USB data once any current connections end.
-
-
For technical details on how this feature works using a combination of hardware
- and software protection, see the section
- on the features page.
GrapheneOS includes our 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 nearly all other apps embedding
- web content or using web technologies for other uses. It's also used by many minor
- web browsers not forking Chromium as a whole. These apps using the WebView benefit
- from a subset of the Vanadium hardening.
-
-
Vanadium was previously primarily focused on security hardening but we plan on
- adding assorted privacy and usability features. In the near future, we plan to add
- support for always incognito mode, improved state partitioning, backup/restore
- and many other features.
-
-
Chromium-based browsers like Vanadium 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, along with strict origin isolation.
-
-
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. 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 does not have internal sandboxing
- on Android. 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) and lacks full support for isolating
- sites from each other rather than only containing content as a whole. The sandbox
- has been gradually improving on the desktop but it isn't happening for their
- Android browser yet.
GrapheneOS has the same camera capabilities and quality as the stock OS. It
- will match the stock OS when comparing the same app on each OS. GrapheneOS uses
- our own modern Camera app rather than the standard AOSP Camera app. GrapheneOS
- Camera is far better than any of the portable open source camera alternatives and
- even most proprietary camera apps including paid apps. On Pixels, Pixel Camera
- can be used as an alternative with more features. The section below has a detailed
- guide on using GrapheneOS Camera and the following section explains the remaining
- advantages of Pixel Camera on Pixels.
GrapheneOS includes our own modern camera app focused on privacy and
- security. It includes modes for capturing images, videos and QR / barcode
- scanning along with additional modes based on CameraX vendor extensions
- (Portrait, HDR, Night, Face Retouch and Auto) on devices
- where they're available (Pixels currently only have support for Night mode).
-
-
Modes are displayed as tabs at the bottom of the screen. You can switch
- between modes using the tab interface or by swiping left/right anywhere on the
- screen. The arrow button at the top of the screen opens the settings panel and
- you can close it by pressing anywhere outside the settings panel. You can also
- swipe down to open the settings and swipe up to close it. Outside of the QR
- scanning mode, there's a row of large buttons above the tab bar for switching
- between the cameras (left), capturing images and starting/stopping video
- recording (middle) and opening the gallery (right). The volume keys can also
- be used as an equivalent to pressing the capture button. While recording a
- video, the gallery button becomes an image capture button for capturing
- images.
-
-
Our Camera app provides the system media intents used by other apps to
- capture images / record videos via the OS provided camera implementation.
- These intents can only be provided by a system app since Android 11, so the
- quality of the system camera is quite important.
-
-
The app has an in-app gallery and video player for images/videos taken with
- it. It currently opens an external editor activity for the edit action.
- GrapheneOS comes with AOSP Gallery which provides an editor activity. You can
- install a nicer photo editor and the Camera app will be able to use it. We
- plan to replace AOSP Gallery with a standalone variant of the gallery we're
- developing for the Camera app in the future.
-
-
Using the default 4:3 aspect ratio for image capture is recommended since
- 16:9 is simply cropped output on all supported devices. A device oriented
- towards video recording might actually have a wider image sensor but that's
- not the case for Pixels or nearly any other smartphone.
-
-
Image capture uses lightweight HDR+ on all supported Pixels and HDRnet for the
- preview on 5th generation Pixels. Using the torch or camera flash will result
- in HDR+ being disabled which is why automatic flash isn't enabled by default.
- The lightweight HDR+ doesn't use as many frames as the more aggressive Pixel
- Camera HDR+. CameraX extensions will eventually provide support for an HDR
- mode with more aggressive HDR+ taking/combining more than only around 3 frames.
- It currently supports a Night mode providing the Night Sight variant of HDR+ inflating
- the light of the scene through combining the frames. Other fancy features like
- Portrait mode will also depend on CameraX extensions being provided in the
- future. There isn't a timeline for when additional CameraX extensions will be added.
-
-
Zooming via pinch to zoom or the zoom slider will automatically make use of
- the wide angle and telephoto cameras on Pixels. 5th and 6th generation Pixels
- (4a (5G), 5, 5a, 6, 6 Pro) have a wide angle camera for zooming out to under
- 1x to capture a much wider field of view. Images taken with the wide angle
- lens won't match the quality of the normal camera, especially with 6th
- generation Pixels. Flagship 4th generation Pixels (4, 4 XL) have a telephoto
- camera providing 2x optical zoom and the Pixel 6 Pro has one providing 4x
- optical zoom.
-
-
By default, continuous auto focus, auto exposure and auto white balance are
- used across the whole scene. Tapping to focus will switch to auto focus, auto
- exposure and auto white balance based on that location. The focus timeout
- setting determines the timeout before it switches back the default mode. The
- exposure compensation slider on the left allows manually tuning exposure and
- will automatically adjust shutter speed, aperture and ISO without disrupting
- lightweight HDR+ support. Further configuration / tuning will be provided in
- the future.
-
-
The QR scanning mode only scans within the scanning square marked on the
- screen. The QR code should be aligned with the edges of the square but can
- have any 90 degree orientation. Non-standard inverted QR codes are fully
- supported. It's a very quick and high quality QR scanner able to easily scan
- very high density QR codes from Pixels. Every 2 seconds, it will refresh auto
- focus, auto exposure and auto white balance on the scanning square. It has
- full support for zooming in and out. The torch can be toggled with the button
- at the bottom center. The auto toggle at the bottom left can be used to toggle
- scanning for all supported barcode types. Alternatively, you can select which
- barcode types it should scan via the menu at the top. It only scans QR codes
- by default since that provides quick and reliable scanning. Most other types
- of barcodes can result in false positives. Each enabled type will slow down
- the scanning and will make it more prone to false positives especially with
- difficult to scan barcodes such as a dense QR code.
-
-
Camera permission is the only one that's required. Images and videos are
- stored via the Media Store API so media/storage permissions aren't required.
- The Microphone permission is needed for video recording by default but not
- when including audio is disabled. Location permission is only needed if you
- explicitly enabling location tagging, which is an experimental feature.
-
-
By default, EXIF metadata is stripped for captured images and only includes
- the orientation. Stripping metadata for videos is planned but not supported
- yet. Orientation metadata isn't stripped since it's fully visible from how the
- image is displayed so it doesn't count as hidden metadata and is needed for
- proper display. You can toggle off stripping EXIF metadata in the More
- Settings menu opened from the settings dialog. Disabling metadata stripping
- will leave the timestamp, phone model, exposure configuration and other
- metadata. Location tagging is disabled by default and won't be stripped if you
- enable it.
-
-
Electronic Image Stabilization (EIS) is enabled by default on devices
- providing it via the Camera2 API and can be disabled using the video settings
- dialog.
-
-
Zero Shutter Lag (ZSL) is available as an opt-in toggle in More Settings
- and speeds up image capture for the Camera mode when flash is disabled.
Pixel Camera (previously known as Google Camera) can take full advantage of the
- available cameras and image processing hardware as it can on the stock OS and does
- not require GSF or sandboxed Google Play on GrapheneOS. Direct TPU and GXP access
- by Google apps including Pixel Camera is controlled by a toggle added by GrapheneOS
- and doesn't provide them with any additional access to data. The toggle exists for
- attack surface reduction. Every app can use the TPU and GXP via standard APIs
- including the Android Neural Networks API and Camera2 API regardless.
-
-
We aim to reduce the benefits of Pixel Camera compared to GrapheneOS
- Camera over time, especially on Pixels. Many features of Pixel Camera will
- end up being available for GrapheneOS Camera in the next year or so via
- CameraX extensions including more aggressive HDR+, Night Sight and Portrait.
- Video features such as slow motion and time lapse are likely further away than
- within the next year. These video features could potentially be provided via
- CameraX vendor extensions or could be implemented via our own post-processing
- of the video output. Panorama, Photo Sphere, Astrophotography, Motion Photos,
- Frequent Faces, Dual Exposure Controls, Google Lens, etc. aren't on the
- roadmap for GrapheneOS Camera. Video frame rate configuration and H.265
- support should be available for GrapheneOS Camera in the near future via
- CameraX improvements along with DNG (RAW) support in the further future.
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 200ms 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.
-
-
This feature can be disabled via Settings >
- Security & privacy >
- Exploit protection > Secure app spawning
- if you prefer to have faster cold start app spawning time and lower app process
- memory usage instead of the substantial security benefits and the removal of the
- only known remaining direct device identifiers across profiles (i.e. not depending
- on fingerprinting global configuration, available storage space, etc. or using side
- channels).
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.
-
-
You can enable our exploit protection compatibility mode via
- Settings > Apps >APP>
- Exploit protection compatibility mode. The exploit protection compatibility mode
- toggle will:
-
-
Switch from hardened_malloc to Android's standard allocator (Scudo)
-
Reduce address space size from 48 bit to Android's standard 39 bit
-
Disable memory tagging, unless the app has opted-in to it (only on
- compatible devices)
-
Allow native debugging (ptrace) access
-
-
-
All of these changes apply only to the selected app and can be toggled separately.
-
-
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 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 default connections FAQ)
- and can be easily disabled or forced through a VPN service.
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 all
- known hidden SSIDs end up being broadcast as part of scanning for networks to
- find them again. SSIDs are not broadcast for standard non-hidden APs. Hidden
- APs are only hidden when no devices are connected. It makes little sense as a
- privacy feature, especially for a non-mobile AP where knowing the AP exists
- can't be used for tracking it since it doesn't move. The feature reduces your
- privacy rather than increasing it. If you need to use a hidden AP, make sure
- to delete the saved network afterwards.
-
-
Wi-Fi and Bluetooth scanning for improving location detection are disabled by
- default, unlike the stock OS. These can be toggled in Settings > Location >
- Location services > 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 itself doesn't currently include a
- supplementary location service based on Wi-Fi and Bluetooth scanning. These
- options impact whether apps such as sandboxed Google Play are able to use the
- functionality if you grant them the Location permission. GrapheneOS plans to
- eventually include an OS service based on local databases rather than a
- network-based service giving the user's location to a server whenever location
- is being used.
Associated MAC randomization is performed by default. This can be controlled
- per-network in Settings > Network
- & internet > Internet >NETWORK> 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".
-
-
In rare cases, broken routers are unable to accept new clients once their
- DHCP table is full instead of clearing the last recently used entry. You can
- work around this by manually clearing the DHCP table via the router
- administration page and can switch to the per-network randomized MAC mode to
- avoid triggering the issue again. This would prevent a router being used in
- any situation where many clients naturally come and go even without
- per-connection MAC randomization and is not generally an issue for any modern
- routers. Per-connection MAC randomization only makes it more likely to find a
- one of the rare routers with this issue.
-
-
The DHCP client uses the anonymity profile rather than sending a hostname
- so it doesn't compromise the privacy offered by MAC randomization. When the
- per-connection MAC randomization added by GrapheneOS is being used, DHCP
- client state is flushed before reconnecting to a network to avoid revealing
- that it's likely the same device as before.
-
-
GrapheneOS also disables support for stable link-local IPv6 addresses, since these
- have the potential to be used as identifiers. It's more sensible to use typical
- link-local address generation based on the (randomized) MAC address since link-local
- devices have access to both. As of Android 11, Android only uses stable link-local
- privacy addresses when MAC randomization is disabled, so we no longer need to disable
- the feature.
For more information on the network location feature and how it works, see the
- features section.
-
-
The setting can be found at Settings >
- Location > Location services > Network location. The available options are using
- Apple's network location service, or a GrapheneOS proxy to that service.
-
-
To use this feature, you need to make sure that you either have Wi-Fi enabled, or that
- Wi-Fi scanning is enabled at Settings >
- Location > Location services > Wi-Fi scanning. Enabling the Wi-Fi scanning setting
- will allow you to use network location even if you disable the global Wi-Fi toggle.
If you have a reliable LTE connection from your carrier, you can reduce attack
- surface by disabling 2G, 3G and 5G connectivity in Settings > Network & internet >
- SIMs >SIM> 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. VoLTE / VoWi-Fi works on GrapheneOS for
- most carriers unless they restrict it to carrier phones. Some carriers may be missing VoWi-Fi due to
- us not including their proprietary apps. Please note that AT&T users may see "5Ge" being used
- when LTE Only mode is enabled as AT&T intentionally mislabel LTE services as "5Ge" to mislead
- users.
-
-
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 both legacy code (2G, 3G) and bleeding
- edge code (5G).
GrapheneOS has a compatibility layer providing the option to install and use
- the official releases of Google Play in the standard app sandbox. Google Play
- receives absolutely no special access or privileges on GrapheneOS as opposed to
- bypassing the app sandbox and receiving a massive amount of highly privileged
- access. Instead, the compatibility layer teaches it how to work within the full
- app sandbox. It also isn't used as a backend for the OS services as it would be
- elsewhere since GrapheneOS doesn't use Google Play even when it's installed.
-
-
Since the Google Play apps are simply regular apps on GrapheneOS, you install
- them within a specific user or work profile and they're only available within that
- profile. Only apps within the same profile can use it and they need to explicitly
- choose to use it. It works the same way as any other app and has no special
- capabilities. As with any other app, it can't access data of other apps and
- requires explicit user consent to gain access to profile data or the standard
- permissions. Apps within the same profile can communicate with mutual consent and
- it's no different for sandboxed Google Play.
-
-
Sandboxed Google Play is close to being fully functional and provides near
- complete compatibility with the app ecosystem depending on Google Play. Only a
- small subset of privileged functionality which we haven't yet ported to different
- approaches with our compatibility layer is unavailable. Some functionality is
- inherently privileged and can't be provided as part of the compatibility
- layer.
-
-
The vast majority of Play services functionality works perfectly including
- dynamically downloaded / updated modules (dynamite modules) and functionality
- provided by modular app components such as Google Play Games. By default, location
- requests are rerouted to a reimplementation of the Play geolocation service
- provided by GrapheneOS. You can disable rerouting and use the standard Play
- services geolocation service instead if you want the Google network location
- service and related features. This shouldn't be needed outside of testing or
- obscure use cases, since GrapheneOS provides its own opt-in
- Network Location feature.
-
-
Our compatibility layer includes full support for the Play Store. Play Store
- services are fully available including in-app purchases, Play Asset Delivery, Play
- Feature Delivery and app / content license checks. It can install, update and
- uninstall apps with the standard approach requiring that the user authorizes it as
- an app source and consents to each action. It will use the standard Android 12+
- unattended update feature to do automatic updates for apps where it was the last
- installer.
The simplest approach is to only use the Owner user profile. Apps installed
- in the Owner profile are sandboxed the same way as everywhere else and don't
- receive any special access. If you want to choose which apps use Google Play
- rather than making it available to all of them, install it in a separate user
- or work profile for apps depending on Google Play. You could also do it the
- other way around, but it makes more sense to try to use as much as possible
- without Google Play rather than treating not using it as the exceptional
- case.
-
-
To install sandboxed Google Play, open our App Store, select Google Play
- services and install it. This will install both Google Play services and Google
- Play Store which are interdependent. Existing installs of sandboxed Google Play
- from before Android 15 will also have Google Services Framework installed and it
- shouldn't be removed.
-
-
Google Play services and Google Play Store are updated through the App Store.
-
-
-
You should give a battery optimization exception to Google Play services
- for features like push notifications to work properly in the background. It
- isn't needed for the Google Play Store app.
-
-
Signing in into a Google account is optional, unless you want to
- use features depending on being signed into an account. For example, some apps
- use Google account authentication instead of their accounts having a username
- and password. The Play Store requires being signed into an account in order to
- install apps or use in-app purchases. This is still true even for an alternate
- frontend to the Play Store. Aurora Store still requires an account but fetches
- shared account credentials from Aurora Store's service by default.
-
-
The Play Store provides many services used by apps including Play Asset
- Delivery, Play Feature Delivery, in-app purchases and license checks for paid
- apps. The Play Store app is also the most secure way to install and update apps
- from the Play Store.
-
-
Our compatibility layer has support for Play Games Services which you can
- obtain by installing Google Play Games from the Play Store. Many games on the
- Play Store depend on having Google Play Games installed.
The compatibility layer has a configuration menu available at
- Settings > Apps > Sandboxed Google Play.
-
-
By default, apps using Google Play geolocation are redirected to our own
- implementation on top of the standard OS geolocation service. You don't need to
- grant any permissions to Google Play or change any settings for working location
- in apps using Google Play geolocation due to our rerouting feature.
-
-
This is not recommended unless you're testing something or have an obscure
- use case since our network location
- feature can be used instead, but if you want to use Google's network location
- service to provide location estimates without satellite reception, you can
- follow these steps:
-
-
-
Disable the "Reroute location requests to OS APIs" toggle.
-
Grant "Allow all the time" Location access to Google Play services along with the
- Nearby Devices permission for it to have all the access it needs.
-
Use the "Google Location Accuracy" link from the sandboxed Google Play configuration
- menu to access the Google Play services menu for opting into their network location service.
-
To take advantage of Wi-Fi and Bluetooth scanning, you also need to enable the scanning
- toggles in Settings >
- Location > Location services
- which are disabled by default and control whether apps with the required permissions
- can scan when Wi-Fi and Bluetooth are otherwise disabled.
-
-
-
Re-routing location to the OS geolocation service will use more power than
- using the Google Play geolocation service unless you enable our opt-in
- network location feature.
-
-
The Google Location Accuracy and Google settings activities would normally
- be integrated into the OS but we don't include any of the standard Google Play
- integration so there needs to be an app providing a way to access them.
-
-
The menu also provides links to this usage guide, Play services system
- settings, Play Store system settings and Google settings. The Play services and
- Play Store system settings are only included for convenience since they can be
- accessed the same way as any other app via Settings > Apps.
Location sharing in Google Maps is implemented in Google Play services. It
- requires enabling both the Location permission with "Allow all the time" and the
- Physical activity permission for Google Play services. Our location rerouting
- feature reimplementing the Google Play location service using the OS location
- service does not apply to Google Play services itself, so Google Play services
- won't use the OS network location service. You can use the instructions above
- for enabling network location via Google Play if you want this. You could
- continue using rerouting for other apps or disable it to avoid needing 2
- separate network location services enabled.
Our compatibility layer has to be expanded on a case-by-case basis to teach
- Play services to work as a regular app without any of the invasive access and
- integration it expects. In many cases, it doesn't truly need the access or we
- can teach it to use the regular approach available to a normal app. In some
- cases, the functionality it offers fundamentally requires privileged access
- and cannot be supported. For example, Android Auto cannot be supported by
- default as part of the baseline compatibility layer, but is supported as an
- extension of it with dedicated toggles for the functionality that's not
- possible to implement another way. The same applies to other highly invasive
- OS integration / control or privileged access to hardware. Our compatibility
- layer is a very actively developed work in progress and most of the remaining
- unavailable functionality is quickly becoming supported. In the future, we can
- also support redirection for more APIs such as FIDO2 rather than only the
- geolocation service.
-
-
Functionality depending on the OS integrating Play services and using it as
- a backend is unavailable. An OS integrating Play uses it as the backend for OS
- services such as geolocation. GrapheneOS never uses it as the backend/provider
- for OS services. In cases such as text-to-speech (TTS) where the OS allows the
- user to choose the provider, Play services can often be used. It's on a level
- playing field with other apps on GrapheneOS.
By default, GrapheneOS has always shipped with baseline support for eSIM,
- where users can use any eSIMs installed previously on the device. However, in
- order to manage and add eSIMs, proprietary Google functionality is needed. This
- is fully disabled by default.
-
-
eSIM support on GrapheneOS doesn't require any dependency on Google Play,
- and never shares data to Google Play even when installed. It won't connect to a
- Google service unless the carrier uses one themselves.
-
-
eSIM support can be enabled in Settings >
- Network & internet >
- eSIM support. The toggle is persistent across every boot.
-
-
Note that if the eSIM installation process does not progress past the
- "Checking network info..." stage despite having a stable Internet connection,
- you may need to call the USSD code *#*#4636#*#* and then enable
- DSDS in the menu that is presented.
-
-
If an eSIM locked with a PIN is used, it is recommended to leave the eSIM
- support toggle enabled even after activating the eSIM. This will allow you to
- disable the eSIM on the lockscreen in case the PIN is forgotten. If the eSIM
- support toggle is disabled and the PIN is forgotten, there is no way to access the
- device unless the PUK is provided.
GrapheneOS provides an option to install and use the official releases of
- Android Auto.
-
-
Android Auto requires privileged access in order to work. GrapheneOS uses
- an extension of the sandboxed Google Play compatibility layer to make Android
- Auto work with a reduced level of privileges.
-
-
To install Android Auto, use the GrapheneOS App Store. Android Auto
- can't be installed through the Play Store or other app sources. Android Auto
- depends on sandboxed Google Play, you'll be prompted to install it if it's not
- already installed.
-
-
After installation, Android Auto has to be set up from the Settings > Apps >
- Sandboxed Google Play > Android Auto
- configuration screen, which contains permission toggles, links to related
- configuration screens, configuration tips, and links to optional Android Auto
- dependencies.
-
-
The permission toggles ask for a confirmation before turning on. The
- confirmation popup explains what access each permission toggle provides.
-
-
By default, Android Auto is not granted any kind of privileged access. It's
- treated the same way other apps are treated.
-
-
In order to work, Android Auto has to be granted baseline permissions for wired
- or wireless Android Auto. Wired Android Auto requires far less access than wireless
- Android Auto does. Baseline permissions are controlled by the "Allow permissions
- for wired / wireless Android Auto" toggles.
-
-
For some cars, baseline permissions for wireless Android Auto are needed even
- when using wired Android Auto. Therefore, if wired Android Auto is unable to
- connect to the car with only wired permissions granted, try granting wireless
- permissions instead.
-
-
To forward notifications from the device to the car, Android Auto has to be
- allowed notification access. The notification access settings are linked below the
- permission toggles.
-
-
In order to show up in the Android Auto car interface, apps have to be installed
- from the Play Store and include Android Auto support.
-
-
See Google's
- Android Auto Help pages for further Android Auto setup steps and usage
- instructions.
Banking apps are a particularly problematic class of apps for compatibility
- with alternate operating systems. Some of these work fine with any GrapheneOS
- configuration but most of them have extensive dependencies on Play services. For
- many of these apps, it's enough to set up the GrapheneOS sandboxed Google Play
- feature in the same profile. Unfortunately, there are further complications not
- generally encountered with non-financial apps.
-
-
Many of these apps have their own crude anti-tampering mechanisms trying to
- prevent inspecting or modifying the app in a weak attempt to hide their code and API
- from security researchers. GrapheneOS allows users to disable Native code
- debugging via a toggle in Settings >
- Security & privacy > Exploit protection
- to improve the app sandbox and this can interfere with apps debugging their
- own code to add a barrier to analyzing the app. You should try enabling this again if you've
- disabled it and are encountering compatibility issues with these kinds of apps.
-
-
Banking apps are increasingly using Google's SafetyNet attestation service to
- check the integrity and certification status of the operating system. GrapheneOS
- passes the basicIntegrity check but isn't certified by Google so it
- fails the ctsProfileMatch check. Most apps currently only enforce
- weak software-based attestation which can be bypassed by spoofing what it checks.
- GrapheneOS doesn't attempt to bypass the checks since it would be very fragile and
- would repeatedly break as the checks are improved. Devices launched with Android 8
- or later have hardware attestation support which cannot be bypassed without leaked
- keys or serious vulnerabilities so the era of being able to bypass these checks by
- spoofing results is coming to an end regardless.
-
-
The hardware attestation feature is part of the Android Open Source Project and
- is fully supported by GrapheneOS. SafetyNet attestation chooses to use it to
- enforce using Google certified operating systems. However, app developers can use
- it directly and permit other properly signed operating systems upholding the
- security model. GrapheneOS has a
- detailed guide for app
- developers on how to support GrapheneOS with the hardware attestation API. Direct
- use of the hardware attestation API provides much higher assurance than using
- SafetyNet so these apps have nothing to lose by using a more meaningful API and
- supporting a more secure OS.
-
-
A 3rd party community-sourced effort containing
- banking
- app compatibility information is maintained by PrivSec.dev. GrapheneOS does
- not make any guarantees regarding the list's validity.
Android apps can declare associations with domains in order to handle those URLs
- in the app automatically. For security reasons, app links are disabled by default to
- prevent apps intercepting arbitrary URLs. First party apps associated with a domain
- are expected to be authorized by the domain. Apps can ask for their app links to be
- verified by the OS by marking them with autoVerify in their manifest.
- The OS will securely confirm that the domain authorizes the app to handle the
- domain's URLs. Users can also manually enable an app's link associations via
- Settings > Apps >APP>
- Open by default > Add link. Apps can ask
- users to enable the associations and send them to this page in the Settings app.
-
-
As an example, the first party YouTube app will have the app links verified by
- the OS automatically while the NewPipe app requires manually enabling handling
- links for YouTube and other sites.
-
-
Verification of app links by the OS is done by the Intent Filter Verification
- Service system app. It will use an HTTPS GET request to fetch
- https://example.com/.well-known/assetlinks.json in order to process a
- request to verify that an app can handle example.com links. The app
- needs to have their app id and signing keys authorized by the domain in order for
- the verification to succeed.
-
-
These network requests by the Intent Filter Verification Service to verify app
- associations with domains are commonly confused for network requests made by the
- apps. It's simply an HTTPS GET request without identifying information and doesn't
- offer a communication channel with the app. Redirects won't be followed so there
- will be a single request for each attempt to verify a domain.
-
-
If you don't want automatic app link verification, you can disable the Network
- permission added by GrapheneOS for the Intent Filter Verification Service system
- app. In the future, we may provide a way to disable verification directly instead
- of stopping it from working. It will make heavily throttled attempts to verify a
- domain after the check failed which won't negatively impact battery life due to
- the conservative JobScheduler-based implementation.
GrapheneOS aims to work with all carriers that are officially supported by
- Google on the stock operating system on Pixel devices. Wi-Fi Calling, VoLTE,
- Visual Voicemail, MMS, SMS, Calling and 5G (SA and NSA) all are supported, however
- some functionality may not be usable due to Google not supporting carriers on the
- stock OS officially or due to GrapheneOS not shipping proprietary apps required in
- order for this functionality to work on some carriers. GrapheneOS extracts
- CarrierConfigs, APNs, modem configurations, Visual Voicemail configurations and
- MMS configurations from the stock operating system to ensure users get easy
- carrier support that "just works".
-
-
Please note that in some regions, LTE is referred to as 4G.
-
-
Generally 5G, SMS, MMS, Calls and VoLTE will work fine on GrapheneOS with
- officially supported carriers by Google. Wi-Fi calling may vary due to a reliance
- on proprietary Google apps which GrapheneOS does not ship.
-
-
If you are having issues with Visual Voicemail, please be aware that AT&T
- USA users are unable to use this feature currently due to a lack of AOSP support.
- Other carriers are done on a best effort basis. We would suggest using Google
- Dialer with sandboxed Google Play if you are unable to get this feature
- working.
-
-
If you are having problems sending or receiving SMS/MMS messages, we suggest
- that you perform the following steps:
Deregister your phone number from your carrier's RCS service (Not all carriers have this)
-
-
-
If you continue to have problems despite following the instructions above or
- you have another carrier related issue, we suggest that you perform the following
- steps:
-
-
-
Some carriers require you to explicitly opt in to use services such as Wi-Fi calling.
- Consult your carrier's documentation on the process for this or contact them.
-
Reset Mobile Network Settings in Settings > System >
- Reset options and then reboot the device.
-
USA users only: You may need to request your carrier to enable CDMA-less mode if
- you have issues.
-
Follow your carrier's instructions for setting up APNs, this can be found in
- Settings > Network &
- internet > SIMs >SIM> Access Point Names
-
If calls do not work and you have LTE-only mode enabled,
- try toggling it off. If "Allow 2G" is disabled, try toggling it back on. Your carrier
- may not properly support VoLTE.
-
As a last resort you may need to ask your carrier for a replacement SIM card.
-
-
-
Some carriers may restrict functionality, such as VoLTE, on imported Pixel
- devices as they only whitelist the IMEI ranges of Pixel device SKUs which were sold
- locally. You can check your SKU on GrapheneOS by going to Settings > About phone >
- Model > Hardware SKU and using the official Google
- documentation. You should check if such functionality works on the stock OS to troubleshoot.
- It is not possible to change the IMEI on a production device and GrapheneOS cannot add support for
- it since the hardware doesn't support it.
-
-
Android 12 introduced support for the
- GSMA
- TS.43 standard where provisioning for VoLTE, VoNR and Wi-Fi calling may be
- handled by Google Firebase. Currently it is very rare for carriers to be using
- Firebase to handle this. It is unlikely, but technically possible, that with such
- carriers you may be required to install sandboxed Google Play in order to obtain
- the former mentioned functionality where the carrier has not implemented fallback
- provisioning via SMS. Currently only US Cellular, Orange France, Cspire US,
- and Cellcom US are using this standard.
-
-
GrapheneOS includes bypasses for carrier restrictions on APN editing, tethering
- via USB, Ethernet, Bluetooth and Wi-Fi and the ability to disable 2G (only on 6th
- generation Pixel devices onwards) actions which would not necessarily have been
- possible on the stock operating system.
Hakurei