aboutsummaryrefslogtreecommitdiff
path: root/docs/depthcharge/index.md
diff options
context:
space:
mode:
authorAlyssa Rosenzweig <alyssa@rosenzweig.io>2017-03-20 20:26:48 -0700
committerAlyssa Rosenzweig <alyssa@rosenzweig.io>2017-03-20 20:26:48 -0700
commita62fe03d3e84150e6186f57f53029d5a9abe3d7b (patch)
tree1a1276b32fcc5388165bd42b685c0d9e83380a7b /docs/depthcharge/index.md
parent07da8fb0c7d513bc73470b69be99f1add0cb95e5 (diff)
downloadlibrebootfr-a62fe03d3e84150e6186f57f53029d5a9abe3d7b.tar.gz
librebootfr-a62fe03d3e84150e6186f57f53029d5a9abe3d7b.zip
undo breakages
Diffstat (limited to 'docs/depthcharge/index.md')
-rw-r--r--docs/depthcharge/index.md107
1 files changed, 59 insertions, 48 deletions
diff --git a/docs/depthcharge/index.md b/docs/depthcharge/index.md
index da8126c7..c9682847 100644
--- a/docs/depthcharge/index.md
+++ b/docs/depthcharge/index.md
@@ -1,7 +1,10 @@
-% Depthcharge payload
+
+Depthcharge payload
+===================
This section relates to the depthcharge payload used in libreboot.
+
- [CrOS security model](#cros_security_model)
- [Developer mode screen](#developer_mode_screen)
- Holding the developer mode screen
@@ -15,6 +18,8 @@ This section relates to the depthcharge payload used in libreboot.
- [Configuring verified boot
parameters](#configuring_verified_boot_parameters)
+
+
CrOS security model {#cros_security_model}
===================
@@ -24,17 +29,20 @@ compromised, that is implemented as the verified boot (vboot) reference,
most of which is executed within depthcharge. A detailed overview of the
CrOS security model is available on the dedicated page.
+
In spite of the CrOS security model, depthcharge won't allow booting
kernels without verifying their signature and booting from external
media or legacy payload unless explicitly allowed: see [configuring
verified boot parameters](#configuring_verified_boot_parameters).
+
+
+
Developer mode screen {#developer_mode_screen}
=====================
The developer mode screen can be accessed in depthcharge when developer
-mode is enabled.
-
+mode is enabled.\
Developer mode can be enabled from the [recovery mode
screen](#recovery_mode_screen).
@@ -43,6 +51,7 @@ external media (when enabled), booting from legacy payload (when
enabled), showing information about the device and disabling developer
mode.
+
Holding the developer mode screen {#holding_developer_mode_screen}
---------------------------------
@@ -50,23 +59,25 @@ As instructed on the developer mode screen, the screen can be held by
pressing **Ctrl + H** in the first 3 seconds after the screen is shown.
After that delay, depthcharge will resume booting normally.
+
+
Booting normally {#booting_normally}
----------------
As instructed on the developer mode screen, a regular boot will happen
-after **3 seconds** (if developer mode screen is not held).
-
+after **3 seconds** (if developer mode screen is not held).\
The default boot medium (internal storage, external media, legacy
payload) is shown on screen.
+
+
Booting from different mediums {#booting_different_mediums}
------------------------------
Depthcharge allows booting from different mediums, when they are allowed
(see [configuring verified boot
parameters](#configuring_verified_boot_parameters) to enable or disable
-boot mediums).
-
+boot mediums).\
As instructed on the developer mode screen, booting from various mediums
can be triggered by pressing various key combinations:
@@ -74,14 +85,17 @@ can be triggered by pressing various key combinations:
- External media: **Ctrl + U** (when enabled)
- Legacy payload: **Ctrl + L** (when enabled)
+
+
Showing device information {#showing_device_information}
--------------------------
As instructed on the developer mode screen, showing device information
-can be triggered by pressing **Ctrl + I** or **Tab**.
-
+can be triggered by pressing **Ctrl + I** or **Tab**.\
Various information is shown, including vboot non-volatile data, TPM
-status, GBB flags and key hashes.
+status, GBB flags and key hashes.\
+
+
Warnings
--------
@@ -92,6 +106,9 @@ The developer mode screen will show warnings when:
- Booting from external media is enabled
- Booting legacy payloads is enabled
+
+
+
Recovery mode screen {#recovery_mode_screen}
====================
@@ -102,27 +119,25 @@ It allows recovering the device from a bad state by booting from a
trusted recovery media. When accessed with the device in a good state,
it also allows enabling developer mode.
+
Recovering from a bad state {#recovering_bad_state}
---------------------------
When the device fails to verify the signature of a piece of the boot
software or when an error occurs, it is considered to be in a bad state
-and will instruct the user to reboot to recovery mode.
-
+and will instruct the user to reboot to recovery mode.\
Recovery mode boots using only software located in write-protected
memory, that is considered to be trusted and safe.
Recovery mode then allows recovering the device by booting from a
trusted recovery media, that is automatically detected when recovery
mode starts. When no external media is found or when the recovery media
-is invalid, instructions are shown on screen.
-
+is invalid, instructions are shown on screen.\
Trusted recovery media are external media (USB drives, SD cards, etc)
that hold a kernel signed with the recovery key.
Google provides images of such recovery media for Chrome OS (which are
-not advised to users as they contain proprietary software).
-
+not advised to users as they contain proprietary software).\
They are signed with Google's recovery keys, that are pre-installed on
the device when it ships.
@@ -131,22 +146,25 @@ replaced. When the recovery private key is available (e.g. when using
self-generated keys), it can be used to sign a kernel for recovery
purposes.
+
+
Enabling developer mode {#enabling_developer_mode}
-----------------------
As instructed on the recovery mode screen, developer mode can be enabled
-by pressing **Ctrl + D**.
-
+by pressing **Ctrl + D**.\
Instructions to confirm enabling developer mode are then shown on
screen.
+
+
+
Configuring verified boot parameters {#configuring_verified_boot_parameters}
====================================
Depthcharge's behavior relies on the verified boot (vboot) reference
implementation, that can be configured with parameters stored in the
-verified boot non-volatile storage.
-
+verified boot non-volatile storage.\
These parameters can be modified with the **crossystem** tool, that
requires sufficient privileges to access the verified boot non-volatile
storage.
@@ -156,8 +174,7 @@ boot non-volatile storage on some devices. **crossystem** and **mosys**
are both free software and their source code is made available by
Google:
[crossystem](https://chromium.googlesource.com/chromiumos/platform/vboot_reference/).
-[mosys](https://chromium.googlesource.com/chromiumos/platform/mosys/).
-
+[mosys](https://chromium.googlesource.com/chromiumos/platform/mosys/).\
These tools are not distributed along with Libreboot yet. However, they
are preinstalled on the device, with ChromeOS.
@@ -166,42 +183,36 @@ of the device**. In particular, disabling kernels signature
verification, external media boot and legacy payload boot can weaken the
security of the device.
+
The following parameters can be configured:
- Kernels signature verification:
- - Enabled with:
-
- # **crossystem dev\_boot\_signed\_only=1**
- - Disabled with:
-
- # **crossystem dev\_boot\_signed\_only=0**
+ - Enabled with:\
+ \# **crossystem dev\_boot\_signed\_only=1**
+ - Disabled with:\
+ \# **crossystem dev\_boot\_signed\_only=0**
- External media boot:
- - Enabled with:
-
- # **crossystem dev\_boot\_usb=1**
- - Disabled with:
-
- # **crossystem dev\_boot\_usb=0**
+ - Enabled with:\
+ \# **crossystem dev\_boot\_usb=1**
+ - Disabled with:\
+ \# **crossystem dev\_boot\_usb=0**
- Legacy payload boot:
- - Enabled with:
-
- # **crossystem dev\_boot\_legacy=1**
- - Disabled with:
-
- # **crossystem dev\_boot\_legacy=0**
+ - Enabled with:\
+ \# **crossystem dev\_boot\_legacy=1**
+ - Disabled with:\
+ \# **crossystem dev\_boot\_legacy=0**
- Default boot medium:
- - Internal storage:
-
- # **crossystem dev\_default\_boot=disk**
- - External media:
+ - Internal storage:\
+ \# **crossystem dev\_default\_boot=disk**
+ - External media:\
+ \# **crossystem dev\_default\_boot=usb**
+ - Legacy payload:\
+ \# **crossystem dev\_default\_boot=legacy**
- # **crossystem dev\_default\_boot=usb**
- - Legacy payload:
- # **crossystem dev\_default\_boot=legacy**
-Copyright © 2015 Paul Kocialkowski <contact@paulk.fr>
+Copyright © 2015 Paul Kocialkowski <contact@paulk.fr>\
Permission is granted to copy, distribute and/or modify this document
under the terms of the Creative Commons Attribution-ShareAlike 4.0
International license or any later version published by Creative