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")
====================================================

* Only TPM version 1.2 is currently supported. It may be possible to
  configure your 2.0 TPM to emulate the 1.2 interface.

* 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

* Unless you're installing AEM to internal disk, TPM SRK password SHOULD
  NOT be set (otherwise tboot will not be able to check whether critical
  parts of RAM were not altered during S3 sleep). Please be aware that by
  installing to internal disk and setting a TPM SRK password, your RAM
  WILL NOT be protected against tampering when your laptop is suspended,
  so make sure it is completely shut down any time an attacker might gain
  physical access.

* When RAM tampering is detected on wake-up from S3 sleep, the default
  tboot policy only prints a warning into its log (`sudo txt-stat`) so
  even if you checked it immediately after each wake-up, the attacker
  might already have exfiltrated your login passphrase. Fix this by
  either using two-factor for desktop login (weak) or create stronger
  Launch Control Policy (LCP) and Verified Launch Policy (LCP) and write
  them into TPM NVRAM -- especially make sure that tboot will forcefully
  halt/reboot the platform if RAM tampering is detected. See tboot docs
  for more information (`/usr/share/doc/tboot`). Creating a small NVRAM
  area for tboot to write last error code might be a good idea for
  debugging crashes on S3 suspend/resume:

  `sudo tpmnv_defindex -i 0x20000002 -s 8 -pv 0 -rl 0x07 -wl 0x07 -p <ownerpw>`

* 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).
  You can check whether your platform includes STM:

    `sudo txt-stat | grep -iA 1 stm`

  Seeing "stm: 0" and "stm_hash" being all zeros means you DO NOT have
  STM. 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
      (ie. 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 to AEM v4
===================

If you have an existing AEM installation, there are a few steps required
after updating AEM packages to version >= 4.0 (available since Qubes R4).

The easiest way to upgrade is to completely reset the TPM 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.

Otherwise, perform a TPM reset (via BIOS) and skip to the "Installation"
section below.

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.

If your tpm has already been owned in the past, you can reset it by running
tpm_clear -z, powering your computer off, and then resetting TPM 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.

Intel documented the required SINIT module depending on your CPU platform in:
http://software.intel.com/en-us/articles/intel-trusted-execution-technology
But DO NOT download the modules besides the SINIT/RACM from here. The download links provide old versions and broken binaries.

You can then download the module and unzip it. All the modules could be
downloaded from:

https://cdrdv2.intel.com/v1/dl/getContent/630744?wapkw=intel%20txt%20sinit%20acm%20revocation%20

Find the module fitting to your platform and rename it to the names mentioned on the intel website link.

Also, make sure you have the latest RACM update, if available (2nd & 3rd gen):
https://software.intel.com/system/files/article/183305/intel-txt-sinit-acm-revocation-tools-guide-rev1-0_2.pdf

It's possible to use 3rd gen SINIT/RACM on 2nd gen platforms. In fact, the
only RACM available at the time of writing is for the 3rd gen, while the 2nd
gen platforms were also affected by the buffer overflow bug in old SINIT
version.

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

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 processes,
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 not static secret **shown on the screen** to
observe (ie. 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. Save and close the file.
  5. Run the command `grub2-mkconfig -o /boot/grub2/grub.cfg` in dom0.
  6. 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 tboot and the SINIT module you
downloaded, which records the Xen, kernel, and initrd versions used in PCRs
17-19 of the TPM for use in sealing and unsealing your secret. If the measured
launch fails for any reason, tboot will fall back to a normal boot and AEM
will not function.

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 --pcr 19

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.

If you get a message that the "PCR sanity check failed" and you are sure you
have saved the right SINIT blob in step 3.a, then check the tboot log for
details. The easiest way to view it is to set "logging=vga vga_delay=10" on
the "multiboot /tboot.gz" line in grub.cfg and reboot. Alternatively, run
`sudo txt-stat` from dom0. For more information, see the tboot readme
(/usr/share/doc/tboot/README on an installed system).

b) If a chunk of your installed RAM seems to be missing after the reboot
(which can be checked by running "xl info" in dom0), do the following:

# echo 'export GRUB_CMDLINE_TBOOT=min_ram=0x2000000' >>/etc/default/grub
# grub2-mkconfig -o /boot/grub2/grub.cfg

Then go to step 4.a again. A discussion of this problem can be found at
http://thread.gmane.org/gmane.comp.boot-loaders.tboot.devel/610/focus=611
and by searching for "min_ram" in the qubes mailing lists.

c) 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, BIOS, 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 toekn 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 (ie. 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