276 lines
18 KiB
HTML
276 lines
18 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en" prefix="og: http://ogp.me/ns#">
|
|
<head>
|
|
<meta charset="utf-8"/>
|
|
<title>Install | GrapheneOS</title>
|
|
<meta name="description" content="Installation instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta name="theme-color" content="#212121"/>
|
|
<meta name="msapplication-TileColor" content="#ffffff"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<meta name="twitter:site" content="@GrapheneOS"/>
|
|
<meta name="twitter:creator" content="@GrapheneOS"/>
|
|
<meta property="og:title" content="GrapheneOS install documentation"/>
|
|
<meta property="og:description" content="Installation instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
|
|
<meta property="og:type" content="website"/>
|
|
<meta property="og:image" content="https://grapheneos.org/opengraph.png"/>
|
|
<meta property="og:image:width" content="512"/>
|
|
<meta property="og:image:height" content="512"/>
|
|
<meta property="og:image:alt" content="GrapheneOS logo"/>
|
|
<meta property="og:url" content="https://grapheneos.org/install"/>
|
|
<meta property="og:site_name" content="GrapheneOS"/>
|
|
<link rel="icon" type="image/vnd.microsoft.icon" href="/favicon.ico"/>
|
|
<link rel="mask-icon" href="/mask-icon.svg" color="#1a1a1a"/>
|
|
<link rel="stylesheet" href="/grapheneos.css?13"/>
|
|
<link rel="manifest" href="/manifest.webmanifest"/>
|
|
<link rel="canonical" href="https://grapheneos.org/install"/>
|
|
</head>
|
|
<body>
|
|
<nav>
|
|
<ul>
|
|
<li><a href="/">GrapheneOS</a></li>
|
|
<li class="active"><a href="/install">Install</a></li>
|
|
<li><a href="/build">Build</a></li>
|
|
<li><a href="/usage">Usage</a></li>
|
|
<!--<li><a href="/faq">FAQ</a></li>-->
|
|
<li><a href="/releases">Releases</a></li>
|
|
<li><a href="/source">Source</a></li>
|
|
<li><a href="/donate">Donate</a></li>
|
|
<li><a href="/contact">Contact</a></li>
|
|
</ul>
|
|
</nav>
|
|
<div id="content">
|
|
<h1 id="install">
|
|
<a href="#install">Install</a>
|
|
</h1>
|
|
|
|
<h2 id="table-of-contents">
|
|
<a href="#table-of-contents">Table of contents</a>
|
|
</h2>
|
|
<ul>
|
|
<li>
|
|
<a href="#prerequisites">Prerequisites</a>
|
|
<ul>
|
|
<li><a href="#obtaining-fastboot">Obtaining fastboot</a></li>
|
|
<li><a href="#obtaining-signify">Obtaining signify</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#enabling-oem-unlocking">Enabling OEM unlocking</a></li>
|
|
<li><a href="#unlocking-the-bootloader">Unlocking the bootloader</a></li>
|
|
<li><a href="#obtaining-factory-images">Obtaining factory images</a></li>
|
|
<li><a href="#flashing-factory-images">Flashing factory images</a></li>
|
|
<li><a href="#locking-the-bootloader">Locking the bootloader</a></li>
|
|
<li><a href="#disabling-oem-unlocking">Disabling OEM unlocking</a></li>
|
|
<li><a href="#verifying-installation">Verifying installation</a></li>
|
|
<li><a href="#replacing-grapheneos-with-the-stock-os">Replacing GrapheneOS with the stock OS</a></li>
|
|
</ul>
|
|
|
|
<h2 id="prerequisites">
|
|
<a href="#prerequisites">Prerequisites</a>
|
|
</h2>
|
|
<p>You should have at least 2GB of free memory available.</p>
|
|
<p>You need the unlocked variant of one of the supported devices, not a locked carrier
|
|
specific variant.</p>
|
|
<p>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. Early
|
|
Pixel 2 and Pixel 2 XL bootloader versions use a non-standard unlocking system not
|
|
covered by these installation instructions. 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 <a href="https://developers.google.com/android/ota">full update package
|
|
page</a>.</p>
|
|
|
|
<h3 id="obtaining-fastboot">
|
|
<a href="#obtaining-fastboot">Obtaining fastboot</a>
|
|
</h3>
|
|
|
|
<p>You need an updated copy of the <code>fastboot</code> tool and it needs to be
|
|
included in your <code>PATH</code> environment variable. You can run <code>fastboot
|
|
--version</code> to determine the current version. It should be at least
|
|
<code>28.0.2</code>. 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.</p>
|
|
|
|
<p>List of distributions with proper packages:</p>
|
|
|
|
<ul>
|
|
<li>Arch Linux: <code>android-tools</code> for fastboot (along with adb and other
|
|
tools, although they aren't necessary to install) and
|
|
<code>android-udev</code> for udev rules to make fastboot / adb work in local
|
|
sessions without root</li>
|
|
</ul>
|
|
|
|
<p>If your distribution doesn't have a proper fastboot package, which is likely,
|
|
consider using the official releases of platform-tools from Google. You can either
|
|
obtain these as part of the standalone SDK or Android Studio which are self-updating
|
|
or via the standalone platform-tools releases. For one time usage, it's easiest to
|
|
obtain the <a href="https://developer.android.com/studio/releases/platform-tools">latest
|
|
standalone platform-tools release</a>, extract it and add it to your <code>PATH</code>
|
|
in the current shell. For example:</p>
|
|
|
|
<pre>unzip platform-tools_r29.0.4-linux.zip
|
|
export PATH="$PWD/platform-tools:$PATH"</pre>
|
|
|
|
<p>Sample output from <code>fastboot --version</code> afterwards:</p>
|
|
|
|
<pre>fastboot version 29.0.4-5871666
|
|
Installed as /home/username/downloads/platform-tools/fastboot</pre>
|
|
|
|
<p>Don't proceed with the installation process until this is set up properly in your
|
|
current shell. A very common mistake is using an outdated copy of
|
|
<code>fastboot</code> from a Linux distribution package not receiving regular updates.
|
|
Make sure that the <code>fastboot</code> found earliest in your <code>PATH</code> is
|
|
the correct one if you have multiple copies on your system. The <code>fastboot
|
|
--version</code> output includes the installation path for the copy of
|
|
<code>fastboot</code> that's being used. Older versions of fastboot do not have support
|
|
for current devices and OS versions. Very old versions of <code>fastboot</code> from
|
|
are still shipped by Linux distributions like Debian and lack the compatibility
|
|
detection of modern versions so they can soft brick devices.</p>
|
|
|
|
<h3 id="obtaining-signify">
|
|
<a href="#obtaining-signify">Obtaining signify</a>
|
|
</h3>
|
|
|
|
<p>To verify the download of the OS beyond the security offered by HTTPS, you need the
|
|
signify tool. If you don't have a way to obtain signify from a trusted package
|
|
repository, such as on Windows, skip the additional verification. This is an important
|
|
step, but it only makes sense if you can chain trust from your existing OS
|
|
install.</p>
|
|
|
|
<p>On many distributions, signify is available via a <code>signify</code> package in
|
|
the official repositories. On Debian-based distributions like Ubuntu, the package and
|
|
command name were renamed to <code>signify-openbsd</code>. Following Debian tradition,
|
|
the <code>signify</code> package and command are an <a
|
|
href="http://signify.sourceforge.net/">unmaintained mail-related tool for generating
|
|
mail signatures (not cryptographic signatures) with the final 3 releases from
|
|
2003-2004 made directly by the developer via the Debian package without upstream
|
|
releases</a>. This is clearly not what you want, but it's easy to end up trying to use
|
|
it instead of <code>signify-openbsd</code>.</p>
|
|
|
|
<h2 id="enabling-oem-unlocking">
|
|
<a href="#enabling-oem-unlocking">Enabling OEM unlocking</a>
|
|
</h2>
|
|
<p>OEM unlocking needs to be enabled from within the operating system.</p>
|
|
<p>Enable the developer options menu by going to Settings ➔ About phone and
|
|
pressing on the build number menu entry until developer mode is enabled.</p>
|
|
<p>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.</p>
|
|
<h2 id="unlocking-the-bootloader">
|
|
<a href="#unlocking-the-bootloader">Unlocking the bootloader</a>
|
|
</h2>
|
|
<p>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.</p>
|
|
<p>The bootloader now needs to be unlocked to allow flashing new images:</p>
|
|
<pre>fastboot flashing unlock</pre>
|
|
<p>The command needs to be confirmed on the device.</p>
|
|
<h2 id="obtaining-factory-images">
|
|
<a href="#obtaining-factory-images">Obtaining factory images</a>
|
|
</h2>
|
|
<p>The initial install will be performed by flashing the factory images. This will
|
|
replace the existing OS installation and wipe all the existing data.</p>
|
|
<p>Download <a href="https://releases.grapheneos.org/factory.pub">the factory images
|
|
public key (factory.pub)</a> in order to verify the factory images.</p>
|
|
<p>This is the content of <code>factory.pub</code>:</p>
|
|
<pre>untrusted comment: GrapheneOS factory images public key
|
|
RWQZW9NItOuQYJ86EooQBxScfclrWiieJtAO9GpnfEjKbCO/3FriLGX3</pre>
|
|
<p>The <code>factory.pub</code> has
|
|
<a href="https://releases.grapheneos.org/factory.pub.asc">a detached signature</a>
|
|
made with the previously used GPG key to verify that this is an authorized key
|
|
rotation. The public key has also been published via the official
|
|
<a href="https://twitter.com/GrapheneOS/status/1145259815851253762">@GrapheneOS Twitter
|
|
account</a>,
|
|
<a href="https://www.reddit.com/r/GrapheneOS/comments/c7gb3f/grapheneos_factory_images_are_now_signed_with/esewpm9">the /u/GrapheneOS
|
|
Reddit account</a> and <a href="https://github.com/GrapheneOS/releases.grapheneos.org/blob/master/static/factory.pub">is available on GitHub</a>.
|
|
When the current signing key is replaced, the new key will be signed with it.</p>
|
|
<p>Download the factory images for the device from <a href="/releases">the releases
|
|
page</a>.</p>
|
|
<p>Verify the factory images using the signature:</p>
|
|
<pre>signify -Cqp factory.pub -x crosshatch-factory-2019.06.23.05.zip.sig && echo verified</pre>
|
|
<h2 id="flashing-factory-images">
|
|
<a href="#flashing-factory-images">Flashing factory images</a>
|
|
</h2>
|
|
<p>Reboot into the bootloader interface to begin the flashing procedure.</p>
|
|
<p>Next, extract the factory images and run the script to flash them. Note that the
|
|
<code>fastboot</code> command run by the flashing script requires a fair bit of free
|
|
space in a temporary directory, which defaults to <code>/tmp</code>:<p>
|
|
<pre>unzip crosshatch-factory-2019.06.23.05.zip
|
|
cd crosshatch-pq3a.190605.003
|
|
./flash-all.sh</pre>
|
|
<p>Use a different temporary directory if your <code>/tmp</code> doesn't have enough
|
|
space available:</p>
|
|
<pre>mkdir tmp
|
|
TMPDIR="$PWD/tmp" ./flash-all.sh</pre>
|
|
<p>Wait for the flashing process to complete and for the device to boot up using the
|
|
new operating system.</p>
|
|
<p>You should now proceed to locking the bootloader before using the device as locking
|
|
wipes the data again.</p>
|
|
<p>On current generation devices like the Pixel 3, Pixel 3 XL, Pixel 3a and Pixel 3a
|
|
XL, you'll need to reboot from the userspace fastbootd mode to the bootloader.</p>
|
|
<h2 id="locking-the-bootloader">
|
|
<a href="#locking-the-bootloader">Locking the bootloader</a>
|
|
</h2>
|
|
<p>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.</p>
|
|
<p>In the bootloader interface, set it to locked:</p>
|
|
<pre>fastboot flashing lock</pre>
|
|
<p>The command needs to be confirmed on the device since it needs to perform a factory
|
|
reset.</p>
|
|
<p>Unlocking the bootloader again will perform a factory reset.</p>
|
|
<h2 id="disabling-oem-unlocking">
|
|
<a href="#disabling-oem-unlocking">Disabling OEM unlocking</a>
|
|
</h2>
|
|
<p>OEM unlocking can be disabled again in the developer settings menu within the
|
|
operating system after booting it up again.</p>
|
|
<h2 id="verifying-installation">
|
|
<a href="#verifying-installation">Verifying installation</a>
|
|
</h2>
|
|
<p>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
|
|
<a href="https://attestation.app/tutorial">Auditor tutorial</a> for a guide.</p>
|
|
<p>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.</p>
|
|
<h2 id="replacing-grapheneos-with-the-stock-os">
|
|
<a href="#replacing-grapheneos-with-the-stock-os">Replacing GrapheneOS with the stock OS</a>
|
|
</h2>
|
|
<p>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.</p>
|
|
<p>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:</p>
|
|
<pre>fastboot erase avb_custom_key</pre>
|
|
</div>
|
|
<footer>
|
|
<a href="/"><img src="https://grapheneos.org/logo.png" width="512" height="512" alt=""/>GrapheneOS</a>
|
|
<ul id="social">
|
|
<li><a href="https://twitter.com/GrapheneOS">Twitter</a></li>
|
|
<li><a href="https://github.com/GrapheneOS">GitHub</a></li>
|
|
<li><a href="https://reddit.com/r/GrapheneOS">Reddit</a></li>
|
|
</ul>
|
|
</footer>
|
|
</body>
|
|
</html>
|