Intro
======

Anti Evil Maid is an implementation of a TPM-based dynamic (Intel TXT) trusted
boot for dracut/initramfs-based OSes (Fedora, Qubes, etc.) with a primary goal
to prevent Evil Maid attacks.

In short, AEM relies on TPM and a feature found in Intel's vPro CPUs (TXT) to
detect tampering of various boot components.

For more information and discussion about potential attacks see:

http://blog.invisiblethings.org/2011/09/07/anti-evil-maid.html
(Note that this article is somewhat outdated, e.g. AEM uses Intel TXT now.)

Requirements and security notes ("before you start")
====================================================

* Both TPM versions 1.2 and 2.0 are supported.

* AEM is not compatible with (U)EFI boot. Legacy boot is required.

* If you are using LUKS with LVM, you must encrypt the whole volume group
  instead of each volume, or else AEM will fail to boot.

* You MUST set a TPM owner password.

* Resume from S3 sleep was not tested on TrenchBoot. S3 in itself opens many
  new attack vectors as many of the security features are disabled when CPU
  comes from reset and must be enabled by firmware. For maximum security, make
  sure your laptop is completely shut down any time an attacker might gain
  physical access.

* Be aware that Intel TXT is vulnerable to System Management Mode (SMM)
  exploits like overwriting System Management Interrupt (SMI) handlers.
  Since SMM code is stored in platform firmware (BIOS) which usually is
  updatable (and thus can be overwritten by an attacker), it is quite
  an attractive target (and not just for the NSA). This can be fixed by
  integrating an SMI Transfer Monitor (STM) into the platform (but this,
  again, relies on the the same BIOS vendor who wrote a buggy SMM code
  to safely implement STM). Additionally, STM does not appear to be
  widely available yet (STM specification released mid-2015 by Intel).
  Either way, BIOS is now part of your Trusted Computing Base (TCB) and
  you need to prevent attackers with physical access from modifying it.
  Good luck.

  Some hints: connect the write protect pin on BIOS flash chip to ground
  (prevents attacker from booting their own software which would bypass
  BIOS protections and overwrite it) and make sure physically accessing
  the chip will be tamper-evident by eg. covering the screws holding
  laptop body together in glitter and taking high-res photos, then
  examining before each use.

* You might want to consider assessing the firmware security of your
  platform using an automated tool such as CHIPSEC:

    https://github.com/chipsec/chipsec

* To recap -- you need to fully trust:
  * CPU (Intel, since we're depending on TXT)
    * sometimes over-optimizes for performance at the cost of security,
      see eg. Meltdown/Spectre, cache attacks against SGX enclaves, ...
  * TPM (various vendors)
    * few known attacks sniffing and injecting commands on the LPC bus;
      differential power analysis; buggy RSA key generation code
    * note that any potential TPM exploits (should) have no means of
      compromising your system directly -- a TPM under attacker's control
      can only be used to hide the fact that a compromise has occurred
      (i.e. defeating the whole AEM feature)
  * BIOS (a few vendors)
    * it's full of holes!
  * that the attacker cannot get physically inside your laptop without
    you noticing (see the glitter hint above)

Upgrading AEM
=============

Pre-v4.2.1 AEM was implemented with Trusted Boot (aka. tboot):

https://sourceforge.net/projects/tboot/

Since v4.2.1 TrenchBoot is used instead:

https://trenchboot.org

TrenchBoot uses Multiboot2 protocol, contrary to tboot's Multiboot. Its logic
is embedded into GRUB2 and Xen, there is no additional stage between those two.
This makes clear distinction between pre- and post-dynamic launch components.

Switching between those two implementations should be straightforward, just
follow "Xen/kernel/BIOS/firmware upgrades" section below.

In case of AEM older than v4, additional steps are required. The easiest way to
upgrade is to completely reset the TPM (via BIOS, depending on vendor this may
require temporarily disabling TXT, make sure to turn it back on afterwards) and
start from scratch and re-create all existing AEM devices.

Should you want to migrate without resetting the TPM (in case you're using
it for something else besides Qubes AEM), you can manually replicate the
steps taken in the TPM setup script (/usr/sbin/anti-evil-maid-tpm-setup).
Note that you still need to re-create all provisioned AEM media afterwards.

Installation
============

The instructions below assume Qubes OS.

1) Enable TPM in BIOS. Also enable TXT if there is an option for it.

2) Install and Verify TPM support under your OS/Dom0.

a) Install anti-evil-maid packages (in Dom0 on Qubes). It will install all the
required dependencies and tools.

# qubes-dom0-update anti-evil-maid

b) Verify kernel support for TPM:

# cat /sys/class/tpm/tpm0/pcrs

If you see something like this:

PCR-00: 67 DC B4 8C AB 8D C7 9B 28 84 D9 15 69 DE 82 F2 F0 E1 2A D8
PCR-01: 11 75 9A 19 E5 BD E8 4E DA 1C 01 EC 53 87 FD 50 18 E1 94 1E
PCR-02: 4B 43 98 82 65 04 E9 F4 14 78 26 F9 ED EA 92 91 6D FD AF D5
PCR-03: B2 A8 3B 0E BF 2F 83 74 29 9A 5B 2B DF C3 1E A9 55 AD 72 36
PCR-04: 93 33 4E 81 A6 9C 80 54 D6 87 C7 FD 76 7C 6F 4C 70 FC C6 73
(...)

... then your TPM is supported by your kernel.

TPM2.0 introduced different hash algorithms to PCRs. Those can be read by:

# cat /sys/class/tpm/tpm0/pcr-sha256/<N>

... where <N> is PCR number, between 0 and 23 inclusive. Different algorithms
may be used in place of 'sha256', but TPM vendors rarely implement anything
beyond SHA1 and SHA256 required by the TPM specification.

If your TPM has already been owned in the past, you can reset it in the BIOS
(e.g.: TPM Authentication Reset).

c) Initialize the TPM for use with AEM

# anti-evil-maid-tpm-setup -z

In case you want to install AEM to an internal disk, an SRK password must
be set up in order for AEM to be secure. The SRK password can be set up
by NOT passing the "-z" option to the above command. Should you not
anticipate future need for internal AEM boot device and want to use
external media only, use the "-z" option. If you later decide to provision
AEM on the internal drive, create an SRK password first:

# tpm_changeownerauth -s

You will need to copy & paste the randomly-generated TPM owner password
from the /var/lib/anti-evil-maid/tpm-owner-pw file. Existing AEM media
will _not_ need to be re-sealed.

3) Setup Anti Evil Maid

a) SINIT module

You should download the SINIT module required for your system. All the modules
could be downloaded from:

https://cdrdv2.intel.com/v1/dl/getContent/630744?explicitVersion=true

Find the module fitting to your platform using the list included in downloaded
archive. Finally, you should retrieve the BIN file inside /boot in dom0. E.g.,
run from dom0:

$ sudo -s
# qvm-run --pass-io vm_name_containing_bin_file 'cat /home/user/path_to_sinit/name_of_sinit_file.BIN' > /boot/name_of_sinit_file.BIN

It is best to keep original file name, both because GRUB configuration script
searches for specific pattern (`*sinit*.bin`, case ignored) and because version
number is included in the name, which should make checking for updates easier.

NOTE: The SINIT files are digitally signed by Intel. While there is no easy
way to verify their integrity after downloading (and after copying to Dom0),
still, the operation of placing such a file into Dom0's /boot filesystem
should be reasonably safe to do -- after all the file should not be processed
by any software in Dom0, and only by the SENTER instruction of the processor,
which, we hope, correctly verifies the signature before executing it...

b) Create an Anti Evil Maid device:

# anti-evil-maid-install -h

Please note that each AEM device you provision should have a unique
filesystem label suffix (use the '-s' option). You may safely re-use
suffixes for destroyed devices.

Installation directly onto a (truly) read-only media (such as a CD-R) is not
supported. You can, however, copy the contents of an existing RW media onto
RO media after the initial sealing takes place. Physical write-protect
switches on USB sticks are fine (install AEM in RW mode, then flip the switch
and proceed to use as RO media). Remember to always pull out the RO media
when your text secret or TOTP code is displayed! Failing to do that will
result in invalidation of freshness token in the TPM memory and the AEM media
will fail to perform verified boot next time, falling back to
non-AEM-protected mode.

For example, to install on the internal boot partition (assuming that it
is /dev/sda1):

# anti-evil-maid-install /dev/sda1

Or better, create an external AEM boot device (in this case an SD card):

# anti-evil-maid-install /dev/mmcblk0p1

Alternatively, a multi-factor authentication AEM boot device can be created,
which provides additional protection against shoulder surfing and video
surveillance -- with the above setups, if an attacker sees your disk
encryption password as you're typing it then they can simply steal and decrypt
your computer. Long story short, if you ever need to boot your AEM-protected
computer in public or anywhere a camera may be hidden, this is the thing you
want to use. However, this setup requires an external boot media (eg. USB
stick or memory card) for maximum protection and owning a suitable two-factor
authentication device supporting time-based one-time passwords (TOTP). There
are apps available for Android/Apple smartphones (Google Authenticator,
FreeOTP Authenticator) and Windows Phone (Microsoft Authenticator). You can
also use a dedicated hardware token, either a reseedable one (letting the AEM
installer generate a seed for you), or a manufacturer-seeded token (you will
need to store the seed in /var/lib/anti-evil-maid/aem<suffix>/secret.otp in
base32 format, then run the AEM installer). The command to set this all up is
simple:

# anti-evil-maid-install -m /dev/sdb1

This will automatically generate a TOTP seed and display it as a QR code for
you to enroll on your 2FA device (if it doesn't have a camera, there's also
text version for manual entry). Once a successful TOTP seed enrollment is
verified (you need to enter the 6-digit code displayed on your 2FA device),
a LUKS key file will be randomly generated and encrypted by a password of
your choice (make sure you're not using this password for anything else).
This key file will then get added to your encrypted drive's LUKS key slot.
For more details, see the associated qubes-devel mailing list thread:
  https://groups.google.com/d/topic/qubes-devel/8cAjSyg1msM/discussion

In case you would like to install multi-factor AEM on internal disk, beware
that keyboard observation attacks cannot be prevented! Plus, you still need
to have TPM SRK password set. The only advantage over plain static text secret
is, of course, that there's no static secret **shown on the screen** to
observe (i.e. cover the keyboard while typing AEM passwords).

If you've chosen to install AEM on an external device (and not the internal
drive), you should then remove the internal boot partition from dom0's
/etc/fstab, never mount it again in dom0, and never boot from it again,
because an attacker might modify it to exploit GRUB or dom0 filesystem
drivers.

Note: If you choose to use a USB device (e.g., a flash drive) as your AEM
device and you previously created a USB qube, then you may have to unhide
your USB controller from dom0:

  1. Open the file `/etc/default/grub` in dom0.
  2. Find the line that begins with `GRUB_CMDLINE_LINUX`.
  3. If present, remove `rd.qubes.hide_all_usb` from that line.
  4. If present, change `usbcore.authorized_default=0` to
     `usbcore.authorized_default=-1`.
  5. Save and close the file.
  6. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
  7. Reboot.

c) Create a secret text (note: it cannot be larger than 255 bytes):

Note: This step is unnecessary if using the multi-factor auth setup, but
can serve as a fallback option in case you ever find yourself temporarily
not having access to your 2FA device (eg. smartphone or hardware TOTP token).

# cat >/var/lib/anti-evil-maid/aem/secret.txt <<END
My secret text
has two lines
END

Note: You are saving this not-yet-sealed secret to your root
filesystem without further encryption (besides that provided by LUKS).
If an attacker somehow gains access to your decrypted filesystem data,
e.g. by compelling you to reveal the LUKS passphrase, they can of
course see these secrets. So they are probably not the right place to
store your most intimate confessions. ;)

4) Reboot the system, choose one of the entries called "AEM Qubes". This will
attempt to perform a "measured launch" using TrenchBoot and the SINIT module
you downloaded, which records the Xen, kernel, and initrd versions used in PCRs
17-18 of the TPM for use in sealing and unsealing your secret. If the measured
launch fails for any reason, TrenchBoot will reboot the platform and AEM entry
will not boot on the next attempt, printing the error code instead. In such
case full power cycle is required to clear that error before AEM boot can be
attempted again.

a) Enter your SRK password if prompted. You won't see your secret afterwards,
because it hasn't been sealed yet (seeing a `Freshness token unsealing
failed!` message here is expected). Enter your disk decryption passphrase
anyway, right now you still trust your system.

As the system continues booting, AEM will automatically seal your
secret(s). You should see a line, or multiple lines, like this one:

Sealed /var/lib/anti-evil-maid/aem/secret.txt using
 --pcr 13 --pcr 17 --pcr 18

Debug output can be read using:

$ journalctl -u anti-evil-maid-unseal -u anti-evil-maid-seal

Note: The PCRs used to seal to can be changed in /etc/anti-evil-maid.conf
-- though the defaults should work just fine. If you decide to change
them and you want to reseal immediately, run anti-evil-maid-seal manually
once.

b) Now, every time you boot your system (from your Anti Evil Maid stick)
you should see your secret text or TOTP code displayed *before* you
enter your LUKS disk encryption or key file passphrase.

Xen/kernel/BIOS/firmware upgrades
=================================

After Xen, kernel, SINIT module, or firmware upgrades, you will need to reboot
and enter your disk decryption passphrase even though you can't see your
secret. Please note that you will see a `Freshness token unsealing failed!`
error. It (along with your AEM secrets) will be resealed again automatically
later in the boot process (see step 4.a).

Some additional things that can cause AEM secrets and freshness token to
fail to unseal (non-exhaustive list):

* changing the LUKS header of the encrypted root partition
* modifying the initrd (adding/removing files or just re-generating it)
* changing kernel commandline parameters in GRUB


What to do in case of compromise
================================

For a discussion of potential attacks against Anti Evil Maid, see the article
referenced at the beginning.


AEM media copied/stolen by an attacker
--------------------------------------

If you have your system up and running or have an extra AEM media using which
you can boot the system before the attacker can get to it:

* `sudo -s` in dom0
* `. /usr/sbin/anti-evil-maid-lib` (note the dot at the beginning)
* `revokefreshness <suffix>` (where `<suffix>` is the missing label suffix)

In case you do not remember the used media label suffix, take a look at
`/var/lib/anti-evil-maid/`. If the particular media had no special suffix set
(i.e. if the subdirectory is just named `aem`), use `revokefreshness ""`.

Alternatively, `resetfreshness` will wipe all freshness tokens from the TPM
(thus invalidating all enrolled AEM media and forcing you to boot an
unverified system).

As a last resort, you can attempt to reset the TPM from BIOS (with similar
effect to `resetfreshness`). Otherwise, it's game over.


Someone saw my LUKS passphrase
------------------------------

You should've installed AEM in multi-factor mode.

If you're fairly confident the attacker does not possess a bitwise copy
of your encrypted Qubes OS drive, change the LUKS passphrase:

* determine the path to LUKS-encrypted disk (usually /dev/sda2)
* add a new password with `sudo cryptsetup luksAddKey <disk>`
* remove old one with `sudo cryptsetup luksRemoveKey <disk>`

As these actions will change the LUKS header, which is fed into one
of the TPM PCRs upon each AEM boot, all the existing AEM media will
get invalidated (i.e. fall back to unverified boot).

Beware that solid-state devices will most likely NOT overwrite the
LUKS header, but rather write the new one into another memory cell
(due to wear leveling algorithms designed to prolong SSD life).
If you're worried about this and have recent-enough backups (as
you always should), perform an ATA secure erase of the whole SSD
using a live CD and then reinstall Qubes OS.
https://ata.wiki.kernel.org/index.php/ATA_Secure_Erase


Someone saw my text secret
--------------------------

Again, if you're going to boot your Qubes OS in public places,
using multi-factor AEM is strongly recommended.

Assuming the attacker haven't yet had access to your computer
(in order to install a compromised bootloader which will show
the correct secret but record your LUKS passphrase), simply
changing the text secret and re-creating affected AEM media
(if you used same secret for multiple ones) will do.

The text secrets are stored in
`/var/lib/anti-evil-maid/aem<suffix>/secret.txt`

Make sure to never trust the old text secret ever again!



TODO: write up more scenarios and how to recover, best practices