From 35da3c2a8f719ab3804de0a30d25257cf413e906 Mon Sep 17 00:00:00 2001 From: Daniel Micay Date: Thu, 8 Sep 2022 06:20:07 -0400 Subject: [PATCH] improve info on verifying installation --- static/install/cli.html | 104 ++++++++++++++++++++++++++++++---------- static/install/web.html | 104 ++++++++++++++++++++++++++++++---------- 2 files changed, 160 insertions(+), 48 deletions(-) diff --git a/static/install/cli.html b/static/install/cli.html index 029a9fb2..55c9f39d 100644 --- a/static/install/cli.html +++ b/static/install/cli.html @@ -103,7 +103,13 @@ @@ -522,31 +528,81 @@ curl -O https://releases.grapheneos.org/DEVICE_NAME-factory-202111012

Verifying installation

-

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 verified boot and attestation features provided by the supported + devices can be used to verify that the hardware, firmware and GrapheneOS + installation are genuine. Even if the computer you used to flash GrapheneOS + was compromised and an attacker replaced GrapheneOS with their own malicious + OS, it can be detected with these features.

-

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 verifies the entirety of the firmware and OS images on every + boot. The public key for the firmware images is burned into fuses in the SoC + at the factory. Firmware security updates can also update the rollback index + burned into fuses to provide rollback protection.

-

After the initial verification, which results in pairing, performing verification - again 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.

+

The final firmware boot stage before the OS is responsible for verifying + it. For the stock OS, it uses a hard-wired public key. Installing GrapheneOS + flashes the GrapheneOS verified boot public key to the secure element. Each + boot, this key is loaded and used to verify the OS. For both the stock OS and + GrapheneOS, a rollback index based on the security patch level is loaded from + the secure element to provide rollback protection.

+ +
+

Verified boot key hash

+ +

When loading an alternate OS, the device shows a yellow notice on boot + with the ID of the alternate OS based on the sha256 of the verified boot + public key. 4th and 5th generation Pixels only show the first 32 bits of + the hash so you can't use this approach. 6th generation Pixels shown the + full hash and you can compare it against the official GrapheneOS verified + boot hashes below:

+ +
    +
  • Pixel 6a: 08c860350a9600692d10c8512f7b8e80707757468e8fbfeea2a870c0a83d6031
    • +
  • Pixel 6 Pro: 439b76524d94c40652ce1bf0d8243773c634d2f99ba3160d8d02aa5e29ff925c
    • +
  • Pixel 6: f0a890375d1405e62ebfd87e8d3f475f948ef031bbf9ddd516d5f600a23677e8
    • +
+ +

Checking this is useful after installation, but you don't need to check + it manually for verified boot to work. The verified boot public key + flashed to the secure element can only be changed when the device is + unlocked. Unlocking the device performs the same wiping of the secure + element as a factory reset and prevents data from being recovered even if + the SSD was cloned and your passphrase(s) are obtained because the + encryption keys can no longer be derived anymore. The verified boot key is + also one of the inputs for deriving the encryption keys in addition to the + user's lock method(s) and random token(s) on the secure element.

+
+ +
+

Hardware-based attestation

+ +

GrapheneOS provides our Auditor app for using a combination of the + verified boot and attestation features to verify that the hardware, + firmware and operating system are genuine along with providing other + useful data from the hardware and operating system.

+ +

Since the purpose of Auditor is to obtain information about the device + without trusting it to be honest, results aren't shown on the device being + verified. You need a 2nd Android device running Auditor for local QR code + based verification. You can also use our optional device integrity + monitoring service for automatic scheduled verifications with support for + email alerts.

+ +

See the Auditor tutorial + for a guide.

+ +

Auditor is primarily based on a pairing model where it generates a + hardware backed signing key and hardware backed attestation signing key + and pins them as part of the initial verification. The first verification + is bootstrapped based on chaining trust to one of the Android attestation + roots. After the first verification, it provides a highly secure system + for obtaining information about the device going forward. An attacker + could bypass the initial verification with a leaked attestation key or by + proxying to another device with the device model, OS and patch level that + the user is expecting. Proxying to another device will be addressed in the + future with optional support for the hardware serial number attestation + feature.

+
diff --git a/static/install/web.html b/static/install/web.html index dc5aef61..34a53210 100644 --- a/static/install/web.html +++ b/static/install/web.html @@ -81,7 +81,13 @@ @@ -331,31 +337,81 @@

Verifying installation

-

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 verified boot and attestation features provided by the supported + devices can be used to verify that the hardware, firmware and GrapheneOS + installation are genuine. Even if the computer you used to flash GrapheneOS + was compromised and an attacker replaced GrapheneOS with their own malicious + OS, it can be detected with these features.

-

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 verifies the entirety of the firmware and OS images on every + boot. The public key for the firmware images is burned into fuses in the SoC + at the factory. Firmware security updates can also update the rollback index + burned into fuses to provide rollback protection.

-

After the initial verification, which results in pairing, performing verification - again 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.

+

The final firmware boot stage before the OS is responsible for verifying + it. For the stock OS, it uses a hard-wired public key. Installing GrapheneOS + flashes the GrapheneOS verified boot public key to the secure element. Each + boot, this key is loaded and used to verify the OS. For both the stock OS and + GrapheneOS, a rollback index based on the security patch level is loaded from + the secure element to provide rollback protection.

+ +
+

Verified boot key hash

+ +

When loading an alternate OS, the device shows a yellow notice on boot + with the ID of the alternate OS based on the sha256 of the verified boot + public key. 4th and 5th generation Pixels only show the first 32 bits of + the hash so you can't use this approach. 6th generation Pixels shown the + full hash and you can compare it against the official GrapheneOS verified + boot hashes below:

+ +
    +
  • Pixel 6a: 08c860350a9600692d10c8512f7b8e80707757468e8fbfeea2a870c0a83d6031
    • +
  • Pixel 6 Pro: 439b76524d94c40652ce1bf0d8243773c634d2f99ba3160d8d02aa5e29ff925c
    • +
  • Pixel 6: f0a890375d1405e62ebfd87e8d3f475f948ef031bbf9ddd516d5f600a23677e8
    • +
+ +

Checking this is useful after installation, but you don't need to check + it manually for verified boot to work. The verified boot public key + flashed to the secure element can only be changed when the device is + unlocked. Unlocking the device performs the same wiping of the secure + element as a factory reset and prevents data from being recovered even if + the SSD was cloned and your passphrase(s) are obtained because the + encryption keys can no longer be derived anymore. The verified boot key is + also one of the inputs for deriving the encryption keys in addition to the + user's lock method(s) and random token(s) on the secure element.

+
+ +
+

Hardware-based attestation

+ +

GrapheneOS provides our Auditor app for using a combination of the + verified boot and attestation features to verify that the hardware, + firmware and operating system are genuine along with providing other + useful data from the hardware and operating system.

+ +

Since the purpose of Auditor is to obtain information about the device + without trusting it to be honest, results aren't shown on the device being + verified. You need a 2nd Android device running Auditor for local QR code + based verification. You can also use our optional device integrity + monitoring service for automatic scheduled verifications with support for + email alerts.

+ +

See the Auditor tutorial + for a guide.

+ +

Auditor is primarily based on a pairing model where it generates a + hardware backed signing key and hardware backed attestation signing key + and pins them as part of the initial verification. The first verification + is bootstrapped based on chaining trust to one of the Android attestation + roots. After the first verification, it provides a highly secure system + for obtaining information about the device going forward. An attacker + could bypass the initial verification with a leaked attestation key or by + proxying to another device with the device model, OS and patch level that + the user is expecting. Proxying to another device will be addressed in the + future with optional support for the hardware serial number attestation + feature.

+