Skip to content

Updates install instructions for UEFI AEM #57

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
+56 −34
Open

Updates install instructions for UEFI AEM #57

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
90 changes: 56 additions & 34 deletions docs/user-docs/install_aem.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,14 +1,22 @@
# Installing TrenchBoot AEM in Qubes OS

This document shows how to install Anti Evil Maid from packages produced by
3mdeb as part of [TrenchBoot as Anti Evil Maid project](https://docs.dasharo.com/projects/trenchboot-aem-v2/).
If you wish to build the components yourself, please refer to documentation for
developers instead.
This document shows how to install Anti Evil Maid from packages produced by 3mdeb
as part of [TrenchBoot as Anti Evil Maid project](https://docs.dasharo.com/projects/trenchboot-aem-v2/).
If you wish to build the components yourself, please refer instead to developer documentation.

## Installation
## Preparing the installation

To install, you have to first add a new repository and import a public part of
a key that was used to sign RPM packages.
Before you begin, it would save installation time by clearing the TPM of your device
before proceeding, otherwise you will need to reboot your computer
at [the provisioning](##Provisioning) step below.
Remember: enable Intel TXT after resetting your TPM.

To install TrenchBoot AME you will need to add a new repository, import a public
part of a key that was used to sign RPM packages, download and install
the appropriate packages, configure a new `.bin` file in the `/boot/`
directory and then configure AEM.

The entire process should take roughly 20 minutes to complete.

### Adding AEM repository

Expand All @@ -24,7 +32,7 @@ gpgkey = https://dl.3mdeb.com/rpm/QubesOS/r4.2/current/dom0/fc37/RPM-GPG-KEY-tb-
enabled = 1
```

The key specified in the file must be downloaded and imported to RPM:
The specified key must be downloaded and imported to RPM:

```bash
qvm-run --pass-io sys-net \
Expand All @@ -33,16 +41,17 @@ qvm-run --pass-io sys-net \
sudo rpm --import RPM-GPG-KEY-tb-aem
```

Now it should be possible to download and install packages from AEM repository.

### Intel systems dependencies

If your device has an Intel CPU, download [official package from Intel](https://cdrdv2.intel.com/v1/dl/getContent/630744)
and extract ACM appropriate for your platform to `/boot/`.
If your device has an Intel CPU, download [the official package from Intel](https://cdrdv2.intel.com/v1/dl/getContent/630744).
Select the correct ACM .bin corresponding to your CPU (using the .PDF
included in the zip as a guide) and move the `.bin` into the dom0 `/boot/` directory.

### Installing prerequisite packages
Helpful commands:
`unzip <zip.acrhive.name>`- to unzip the Intel .zip archive.
`mv <ACM.bin> /boot/` - to move the correct ACM to `/boot`.

#### Qubes repository dependencies
### Installing prerequisite packages

Start by installing prerequisite packages. Those are not part of newly added
repository, but `qubes-dom0-current-testing`:
Expand All @@ -59,7 +68,9 @@ sudo qubes-dom0-update --enablerepo=qubes-dom0-current-testing \

#### Prepare a list of AEM packages

For convenience, the packages can be saved to an environment variable:
For convenience, the packages can be saved to an environment variable,
by simply typing into the dom0 terminal, or copying a text file
from a disposable qube:

```shell
packages=(
Expand Down Expand Up @@ -112,14 +123,18 @@ packages+=(
#### Installing

Install the packages (first command reinstalls existing packages in case the
same version numbers exist on official Qubes repositories, second one only
adds new packages):
same version numbers exist in official Qubes repositories, second one only
adds new packages). If the first command fails, it means that there are no
conflicting packages with the same version number in official Qubes repositories:

```shell
qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall -y ${packages[@]}
qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=install -y ${packages[@]}
sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=reinstall -y ${packages[@]}
sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem --action=install -y ${packages[@]}
```

At this point, if you are installing on an UEFI system,
you may skip to [Installing main AEM package](###Installing-main-AEM-package)

#### Updating GRUB on legacy systems

Booting on legacy systems requires manual installation of GRUB2 to the MBR
Expand Down Expand Up @@ -194,28 +209,34 @@ sudo qubes-dom0-update --disablerepo="*" --enablerepo=aem \

## Provisioning

All packages are in place. Before we can proceed with provisioning AEM, the TPM
must be cleared in the BIOS. Some platforms may require disabling Intel Trusted
Execution Technology (TXT) in order to clear TPM. After you clear the TPM,
remember to enable Intel TXT back, otherwise AEM will not work. Once TPM is
cleared, perform the TPM setup:
All packages are now installed.

Before we can proceed with provisioning AEM, the TPM must be cleared in the BIOS
(i.e. TPM Authentication Reset).Some platforms may require disabling Intel's
Trusted Execution Technology (TXT) in order to clear the TPM.

If you failed to clear the TPM as noted at the beginning of the guide,
you will be shown a message like this:

![](../img/qubes_aem_setup_fail.png)

In that case, try clearing the TPM in your BIOS and run the command again.
After you clear the TPM, remember to enable Intel TXT back,
otherwise AEM will not work.

Once the TPM is cleared, perform the TPM setup:

```bash
sudo anti-evil-maid-tpm-setup
```

![](../img/qubes_aem_setup.png)

You will be prompted to set the SRK password, it is a password to access TPM’s
nonvolatile storage where the AEM secrets will be sealed. If you failed to
clear the TPM, you will be shown a message like this:
You will be prompted to set the SRK password. The SRK password enables access
the TPM’s nonvolatile storage where the AEM secrets will be sealed.

![](../img/qubes_aem_setup_fail.png)

In that case, try clearing the TPM in your BIOS and run the command again.

Now all that's left is proper installation of AEM. There are different options,
refer to `anti-evil-maid-install -h` for examples. In the simplest case, AEM is
Now all that's left is proper installation of AEM. (Note: There are different options,
refer to `anti-evil-maid-install -h` for examples.) In the simplest case, AEM is
installed on boot partition (not disk, i.e. `sda1` instead of `sda` etc.) of
Qubes OS. Run this command to find out where your boot partition is installed:

Expand All @@ -234,11 +255,12 @@ sudo anti-evil-maid-install /dev/sda1

After that, reboot the platform. On first boot you will be asked for the SRK
password, followed by another question for disk encryption password, after which
a screen mentioning absent secret file will be shown:
a screen mentioning an absent secret file will be shown:

![](../img/qubes_aem_1st_boot.png)

This is expected on the first boot after installation or an update to one or
more of measured components (GRUB, Xen, dom0 kernel and initramfs).

After rebooting for the second time, the Anti Evil Maid should be up
and running.