You should have at least 2GB of free memory available.
+You should have at least 2GB of free memory available.
-Windows 10, macOS Catalina, Arch Linux, Debian buster and Ubuntu 20.04 LTS are the - officially supported operating systems for installing GrapheneOS. You should make sure - your operating system is up-to-date before proceeding with these instructions. Older - versions and other Linux distributions usually work, but if you encounter problems try - using one of the officially supported options.
+Windows 10, macOS Catalina, Arch Linux, Debian buster and Ubuntu 20.04 LTS are the + officially supported operating systems for installing GrapheneOS. You should make sure + your operating system is up-to-date before proceeding with these instructions. Older + versions and other Linux distributions usually work, but if you encounter problems try + using one of the officially supported options.
-You need one of the officially supported devices. To make sure that the device can - be unlocked to install GrapheneOS, avoid carrier variants of the devices. Carrier - variants of Pixels use the same stock OS and firmware with a non-zero carrier id - flashed onto the persist partition in the factory. The carrier id activates - carrier-specific configuration in the stock OS including disabling carrier and - bootloader unlocking. The carrier may be able to remotely disable this, but their - support staff may not be aware and they probably won't do it. Get a carrier agnostic - device to avoid the risk and potential hassle. If you CAN figure out a way to unlock a - carrier device, it isn't a problem as GrapheneOS can just ignore the carrier id and - it's otherwise the same.
+You need one of the officially supported devices. To make sure that the device can + be unlocked to install GrapheneOS, avoid carrier variants of the devices. Carrier + variants of Pixels use the same stock OS and firmware with a non-zero carrier id + flashed onto the persist partition in the factory. The carrier id activates + carrier-specific configuration in the stock OS including disabling carrier and + bootloader unlocking. The carrier may be able to remotely disable this, but their + support staff may not be aware and they probably won't do it. Get a carrier agnostic + device to avoid the risk and potential hassle. If you CAN figure out a way to unlock a + carrier device, it isn't a problem as GrapheneOS can just ignore the carrier id and + it's otherwise the same.
-It's best practice to update the stock OS on the device to make sure it's running - the latest firmware before proceeding with these instructions. This avoids running - into bugs, missing features or other differences in older firmware versions. You can - either update the device via over-the-air updates or sideload a full update, which for - Pixel phones can be obtained from the - full update package page.
+It's best practice to update the stock OS on the device to make sure it's running + the latest firmware before proceeding with these instructions. This avoids running + into bugs, missing features or other differences in older firmware versions. You can + either update the device via over-the-air updates or sideload a full update, which for + Pixel phones can be obtained from the + full update package page.
-These instructions use command-line tools. On Windows, use PowerShell rather than - the legacy Command Prompt.
+These instructions use command-line tools. On Windows, use PowerShell rather than + the legacy Command Prompt.
-You need an updated copy of the fastboot tool and it needs to be
- included in your PATH environment variable. You can run fastboot
- --version to determine the current version. It must be at least
- 29.0.6. You can use a distribution package for this, but most of them
- mistakenly package development snapshots of fastboot, clobber the standard version
- scheme for platform-tools (adb, fastboot, etc.) with their own scheme and don't keep
- it up-to-date despite that being crucial.
You need an updated copy of the fastboot tool and it needs to be
+ included in your PATH environment variable. You can run fastboot
+ --version to determine the current version. It must be at least
+ 29.0.6. You can use a distribution package for this, but most of them
+ mistakenly package development snapshots of fastboot, clobber the standard version
+ scheme for platform-tools (adb, fastboot, etc.) with their own scheme and don't keep
+ it up-to-date despite that being crucial.
List of distribution packages:
+List of distribution packages:
-android-tools provides fastboot and other useful
- tools not required for installation such as adb. android-udev
- provides udev rules allowing fastboot and adb to work in local sessions
- without root.android-sdk-platform-tools-common provides
- udev rules allowing fastboot and adb to work in local sessions without root.
- The udev rules in Debian and Ubuntu are out-of-date, but it has the necessary
- entries for Pixel phones. The adb and fastboot packages are currently both
- broken and far too out-of-date to be any use, so avoid those. The version
- check in the flashing script will prevent accidentally using these.android-tools provides fastboot and other useful
+ tools not required for installation such as adb. android-udev
+ provides udev rules allowing fastboot and adb to work in local sessions
+ without root.android-sdk-platform-tools-common provides
+ udev rules allowing fastboot and adb to work in local sessions without root.
+ The udev rules in Debian and Ubuntu are out-of-date, but it has the necessary
+ entries for Pixel phones. The adb and fastboot packages are currently both
+ broken and far too out-of-date to be any use, so avoid those. The version
+ check in the flashing script will prevent accidentally using these.If your operating system doesn't make a proper version of fastboot available, - consider using the - standalone - releases of platform-tools from Google. If you have the Android SDK or intend to - do development work, you install the platform-tools package via the Android SDK - package manager which can be used to keep it up-to-date. The Android SDK is available - by itself or can be obtained via Android Studio.
+If your operating system doesn't make a proper version of fastboot available, + consider using the + standalone + releases of platform-tools from Google. If you have the Android SDK or intend to + do development work, you install the platform-tools package via the Android SDK + package manager which can be used to keep it up-to-date. The Android SDK is available + by itself or can be obtained via Android Studio.
-To download, verify and extract the standalone platform-tools on Linux:
+To download, verify and extract the standalone platform-tools on Linux:
-curl -O https://dl.google.com/android/repository/platform-tools_r30.0.5-linux.zip +curl -O https://dl.google.com/android/repository/platform-tools_r30.0.5-linux.zip echo 'd6d72d006c03bd55d49b6cef9f00295db02f0a31da10e121427e1f4cb43e7cb9 platform-tools_r30.0.5-linux.zip' | sha256sum -c unzip platform-tools_r30.0.5-linux.zip-To download, verify and extract the standalone platform-tools on macOS:
+To download, verify and extract the standalone platform-tools on macOS:
-curl -O https://dl.google.com/android/repository/eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip +curl -O https://dl.google.com/android/repository/eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip echo 'SHA256 (eabcd8b4b7ab518c6af9c941af8494072f17ec4b.platform-tools_r30.0.5-darwin.zip) = e5780bad71a53cf9d693e1053a0748f49e4a67cc1f71d16a94ab4c943af3345f' | shasum -c tar xvf fbad467867e935dce68a0296b00e6d1e76f15b15.platform-tools_r30.0.5-darwin.zip-To download, verify and extract the standalone platform-tools on Windows:
+To download, verify and extract the standalone platform-tools on Windows:
-curl.exe -O https://dl.google.com/android/repository/platform-tools_r30.0.5-windows.zip +curl.exe -O https://dl.google.com/android/repository/platform-tools_r30.0.5-windows.zip (Get-FileHash platform-tools_r30.0.5-windows.zip).hash -eq "549ba2bdc31f335eb8a504f005f77606a479cc216d6b64a3e8b64c780003661f" tar xvf platform-tools_r30.0.5-windows.zip-Next, add the tools to your
+PATHin the current shell so they can be - used without referencing them by file path, enabling usage by the flashing script.Next, add the tools to your
-PATHin the current shell so they can be + used without referencing them by file path, enabling usage by the flashing script.On Linux and macOS:
+On Linux and macOS:
-export PATH="$PWD/platform-tools:$PATH"+export PATH="$PWD/platform-tools:$PATH"-On Windows:
+On Windows:
-$env:Path = "$pwd\platform-tools;$env:Path"+$env:Path = "$pwd\platform-tools;$env:Path"-Sample output from
+fastboot --versionafterwards:Sample output from
-fastboot --versionafterwards:fastboot version 30.0.5-6877874 +fastboot version 30.0.5-6877874 Installed as /home/username/downloads/platform-tools/fastboot-This is a temporary change to
+PATHfor the current shell and will need - to be done again if you open a new terminal. Make sure that thefastboot- command works in the current shell before trying to run the flashing script.This is a temporary change to
+PATHfor the current shell and will need + to be done again if you open a new terminal. Make sure that thefastboot+ command works in the current shell before trying to run the flashing script.
To verify the download of the OS beyond the security offered by HTTPS, you can use - the signify tool. If you do not have a way to obtain signify from a package repository - you're already trusting, it does not make sense to use it. GrapheneOS releases are - hosted on our servers and we do not have third party mirrors. A compromised signify - would be able to compromise your OS and the GrapheneOS download due to the lack of an - application security model on traditional operating systems. It would be worse than - not trying to verify the signatures. It's far less likely that our servers would be - compromised than someone's GitHub account or GitHub itself. You're already trusting - these installation instructions from our site, which is hosted on the same static web - server infrastructure as the releases.
+To verify the download of the OS beyond the security offered by HTTPS, you can use + the signify tool. If you do not have a way to obtain signify from a package repository + you're already trusting, it does not make sense to use it. GrapheneOS releases are + hosted on our servers and we do not have third party mirrors. A compromised signify + would be able to compromise your OS and the GrapheneOS download due to the lack of an + application security model on traditional operating systems. It would be worse than + not trying to verify the signatures. It's far less likely that our servers would be + compromised than someone's GitHub account or GitHub itself. You're already trusting + these installation instructions from our site, which is hosted on the same static web + server infrastructure as the releases.
-List of distribution packages:
+List of distribution packages:
-signifysignify-openbsd with the command renamed to signify-openbsdsignify-openbsd with the command renamed to signify-openbsdsignifysignify-openbsd with the command renamed to signify-openbsdsignify-openbsd with the command renamed to signify-openbsdOn Debian-based distributions, the signify package and command are an
- unmaintained mail-related
- tool for generating mail signatures (not cryptographic signatures) with the final
- releases from 2003-2004 made directly by the developer via the Debian package without
- upstream releases. Please pressure them to correct this usability issue.
On Debian-based distributions, the signify package and command are an
+ unmaintained mail-related
+ tool for generating mail signatures (not cryptographic signatures) with the final
+ releases from 2003-2004 made directly by the developer via the Debian package without
+ upstream releases. Please pressure them to correct this usability issue.
OEM unlocking needs to be enabled from within the operating system.
+OEM unlocking needs to be enabled from within the operating system.
-Enable the developer options menu by going to Settings ➔ About phone and - pressing on the build number menu entry until developer mode is enabled.
+Enable the developer options menu by going to Settings ➔ About phone and + pressing on the build number menu entry until developer mode is enabled.
-Next, go to Settings ➔ System ➔ Advanced ➔ Developer options and toggle on the - 'Enable OEM unlocking' setting. This requires internet access on devices with Google - Play services as part of Factory Reset Protection (FRP) for anti-theft protection.
+Next, go to Settings ➔ System ➔ Advanced ➔ Developer options and toggle on the + 'Enable OEM unlocking' setting. This requires internet access on devices with Google + Play services as part of Factory Reset Protection (FRP) for anti-theft protection.
+First, boot into the bootloader interface. You can do this by turning off the - device and then turning it on by holding both the Volume Down and Power buttons.
+First, boot into the bootloader interface. You can do this by turning off the + device and then turning it on by holding both the Volume Down and Power buttons.
-Unlock the bootloader to allow flashing the OS and firmware:
+Unlock the bootloader to allow flashing the OS and firmware:
-fastboot flashing unlock+
fastboot flashing unlock-
The command needs to be confirmed on the device and will wipe all data.
+The command needs to be confirmed on the device and will wipe all data.
+You need to obtain the GrapheneOS factory images for your device to proceed with - the installation process.
+You need to obtain the GrapheneOS factory images for your device to proceed with + the installation process.
-You can either download the files with your browser or using a command like
- curl. It's generally easier to use the command-line since you're already
- using it for the rest of the installation process, so these instructions use
- curl.
You can either download the files with your browser or using a command like
+ curl. It's generally easier to use the command-line since you're already
+ using it for the rest of the installation process, so these instructions use
+ curl.
On Windows, remove PowerShell's legacy curl alias for the current shell to avoid
- needing to reference it as curl.exe instead of curl:
On Windows, remove PowerShell's legacy curl alias for the current shell to avoid
+ needing to reference it as curl.exe instead of curl:
Remove-Item Alias:Curl+
Remove-Item Alias:Curl-
Download the factory images - public key (factory.pub) in order to verify the factory images:
+Download the factory images + public key (factory.pub) in order to verify the factory images:
-curl -O https://releases.grapheneos.org/factory.pub+
curl -O https://releases.grapheneos.org/factory.pub-
This is the content of factory.pub:
This is the content of factory.pub:
untrusted comment: GrapheneOS factory images public key +untrusted comment: GrapheneOS factory images public key RWQZW9NItOuQYJ86EooQBxScfclrWiieJtAO9GpnfEjKbCO/3FriLGX3-The public key has also been published via the official - @GrapheneOS Twitter - account, - the /u/GrapheneOS - Reddit account and is available on GitHub. - When the current signing key is replaced, the new key will be signed with it.
+The public key has also been published via the official + @GrapheneOS Twitter + account, + the /u/GrapheneOS + Reddit account and is available on GitHub. + When the current signing key is replaced, the new key will be signed with it.
-Download the factory images for the device from the releases - page. For example, to download the 2020.11.05.18 release for the Pixel 4a (sunfish):
+Download the factory images for the device from the releases + page. For example, to download the 2020.11.05.18 release for the Pixel 4a (sunfish):
-curl -O https://releases.grapheneos.org/sunfish-factory-2020.11.05.18.zip +curl -O https://releases.grapheneos.org/sunfish-factory-2020.11.05.18.zip curl -O https://releases.grapheneos.org/sunfish-factory-2020.11.05.18.zip.sig-Verify the factory images using the signature if you were able to obtain -
+signifyfrom trusted package repositories (see above):Verify the factory images using the signature if you were able to obtain +
-signifyfrom trusted package repositories (see above):signify -Cqp factory.pub -x sunfish-factory-2020.11.05.18.zip.sig && echo verified+signify -Cqp factory.pub -x sunfish-factory-2020.11.05.18.zip.sig && echo verified-This will output
+verifiedif verification is successful. If something - goes wrong, it will output an error message rather thanverified.This will output
+verifiedif verification is successful. If something + goes wrong, it will output an error message rather thanverified.
The initial install will be performed by flashing the factory images. This will - replace the existing OS installation and wipe all the existing data.
+The initial install will be performed by flashing the factory images. This will + replace the existing OS installation and wipe all the existing data.
-Next, extract the factory images.
+Next, extract the factory images.
-On Linux:
+On Linux:
-unzip sunfish-factory-2020.11.05.18.zip+
unzip sunfish-factory-2020.11.05.18.zip-
On macOS and Windows:
+On macOS and Windows:
-tar xvf sunfish-factory-2020.11.05.18.zip+
tar xvf sunfish-factory-2020.11.05.18.zip-
Move into the directory:
+Move into the directory:
-cd sunfish-factory-2020.11.05.18+
cd sunfish-factory-2020.11.05.18-
Flash the images with the flash-all script in the directory.
+Flash the images with the flash-all script in the directory.
-On Linux and macOS:
+On Linux and macOS:
-./flash-all.sh+
./flash-all.sh-
On Windows:
+On Windows:
-./flash-all.bat+
./flash-all.bat-
Wait for the flashing process to complete and proceed to locking the bootloader - before using the device as locking wipes the data again.
+Wait for the flashing process to complete and proceed to locking the bootloader + before using the device as locking wipes the data again.
-A common issue on Linux distributions is that they mount the default temporary file
- directory /tmp as tmpfs which results in it being backed by memory and
- swap rather than persistent storage. By default, the size is 50% of the available
- virtual memory. This is often not enough for the flashing process, especially since
- /tmp is shared between applications and users. To use a different
- temporary directory if your /tmp doesn't have enough space available:
A common issue on Linux distributions is that they mount the default temporary file
+ directory /tmp as tmpfs which results in it being backed by memory and
+ swap rather than persistent storage. By default, the size is 50% of the available
+ virtual memory. This is often not enough for the flashing process, especially since
+ /tmp is shared between applications and users. To use a different
+ temporary directory if your /tmp doesn't have enough space available:
mkdir tmp +mkdir tmp TMPDIR="$PWD/tmp" ./flash-all.sh-A majority of failed flashes tend to be caused by substandard USB connectors, - plugging in via hubs or bad cables which aren't properly up to the USB standard. The - scrollback from a failed flash will contain valuable diagnostic information which - is essential in knowing where and how the process went wrong.
+A majority of failed flashes tend to be caused by substandard USB connectors, + plugging in via hubs or bad cables which aren't properly up to the USB standard. The + scrollback from a failed flash will contain valuable diagnostic information which + is essential in knowing where and how the process went wrong.
-Front I/O ports on desktop computer cases and USB 3.1 or USB C on many laptops - often aren't implemented properly or are broken in subtle ways, which may cause flashing - to fail even on a USB port that works for other peripherals. Older Linux kernels that - predate version 5 may have inadequate or patchwork support for USB C or USB 3. If you - are installing from a Linux distribution, ensure your distribution uses a modern - kernel.
+Front I/O ports on desktop computer cases and USB 3.1 or USB C on many laptops + often aren't implemented properly or are broken in subtle ways, which may cause flashing + to fail even on a USB port that works for other peripherals. Older Linux kernels that + predate version 5 may have inadequate or patchwork support for USB C or USB 3. If you + are installing from a Linux distribution, ensure your distribution uses a modern + kernel.
-Always use a high quality USB A to USB C cable with a rear USB port directly on your - motherboard, and never use a USB hub for flashing. Never install from a virtual - machine; USB passthrough in software emulation may be broken or inadequate and this - can cause the flashing to fail.
+Always use a high quality USB A to USB C cable with a rear USB port directly on your + motherboard, and never use a USB hub for flashing. Never install from a virtual + machine; USB passthrough in software emulation may be broken or inadequate and this + can cause the flashing to fail.
+
Locking the bootloader is important as it enables full verified boot. It also - prevents using fastboot to flash, format or erase partitions. Verified boot will - detect modifications to any of the OS partitions (vbmeta, boot/dtbo, product, system, - vendor) and it will prevent reading any modified / corrupted data. If changes are - detected, error correction data is used to attempt to obtain the original data at - which point it's verified again which makes verified boot robust to non-malicious - corruption.
+Locking the bootloader is important as it enables full verified boot. It also + prevents using fastboot to flash, format or erase partitions. Verified boot will + detect modifications to any of the OS partitions (vbmeta, boot/dtbo, product, system, + vendor) and it will prevent reading any modified / corrupted data. If changes are + detected, error correction data is used to attempt to obtain the original data at + which point it's verified again which makes verified boot robust to non-malicious + corruption.
-In the bootloader interface, set it to locked:
+In the bootloader interface, set it to locked:
-fastboot flashing lock+
fastboot flashing lock-
The command needs to be confirmed on the device since it needs to perform a factory - reset.
+The command needs to be confirmed on the device since it needs to perform a factory + reset.
-Unlocking the bootloader again will perform a factory reset.
+Unlocking the bootloader again will perform a factory reset.
+OEM unlocking can be disabled again in the developer settings menu within the - operating system after booting it up again.
+OEM unlocking can be disabled again in the developer settings menu within the + operating system after booting it up again.
+Verified boot authenticates and validates the firmware images and OS from the - hardware root of trust. Since GrapheneOS supports full verified boot, the OS images - are entirely verified. However, it's possible that the computer you used to flash the - OS was compromised, leading to flashing a malicious verified boot public key and - images. To detect this kind of attack, you can use the Auditor app included in - GrapheneOS in the Auditee mode and verify it with another Android device in the - Auditor mode. The Auditor app works best once it's already paired with a device and - has pinned a persistent hardware-backed key and the attestation certificate chain. - However, it can still provide a bit of security for the initial verification via the - attestation root. Ideally, you should also do this before connecting the device to the - network, so an attacker can't proxy to another device (which stops being possible - after the initial verification). Further protection against proxying the initial - pairing will be provided in the future via optional support for ID attestation to - include the serial number in the hardware verified information to allow checking - against the one on the box / displayed in the bootloader. See the - Auditor tutorial for a guide.
+Verified boot authenticates and validates the firmware images and OS from the + hardware root of trust. Since GrapheneOS supports full verified boot, the OS images + are entirely verified. However, it's possible that the computer you used to flash the + OS was compromised, leading to flashing a malicious verified boot public key and + images. To detect this kind of attack, you can use the Auditor app included in + GrapheneOS in the Auditee mode and verify it with another Android device in the + Auditor mode. The Auditor app works best once it's already paired with a device and + has pinned a persistent hardware-backed key and the attestation certificate chain. + However, it can still provide a bit of security for the initial verification via the + attestation root. Ideally, you should also do this before connecting the device to the + network, so an attacker can't proxy to another device (which stops being possible + after the initial verification). Further protection against proxying the initial + pairing will be provided in the future via optional support for ID attestation to + include the serial number in the hardware verified information to allow checking + against the one on the box / displayed in the bootloader. See the + Auditor tutorial for a guide.
-After the initial verification, which results in pairing, performing verification - against between the same Auditor and Auditee (as long as the app data hasn't been - cleared) will provide strong validation of the identity and integrity of the - device. That makes it best to get the pairing done right after installation. You can - also consider setting up the optional remote attestation service.
+After the initial verification, which results in pairing, performing verification + against between the same Auditor and Auditee (as long as the app data hasn't been + cleared) will provide strong validation of the identity and integrity of the + device. That makes it best to get the pairing done right after installation. You can + also consider setting up the optional remote attestation service.
+Installation of the stock OS via the stock factory images is the same process - described above. However, before locking, there's an additional step to fully revert - the device to a clean factory state.
+Installation of the stock OS via the stock factory images is the same process + described above. However, before locking, there's an additional step to fully revert + the device to a clean factory state.
-The GrapheneOS factory images flash a non-stock Android Verified Boot key which - needs to be erased to fully revert back to a stock device state. After flashing the - stock factory images and before locking the bootloader, you should erase the custom - Android Verified Boot key to untrust it:
+The GrapheneOS factory images flash a non-stock Android Verified Boot key which + needs to be erased to fully revert back to a stock device state. After flashing the + stock factory images and before locking the bootloader, you should erase the custom + Android Verified Boot key to untrust it:
-fastboot erase avb_custom_key+
fastboot erase avb_custom_key+