Intro
======

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

For more information and discussion about potential attacks see:

http://theinvisiblethings.blogspot.com/2011/09/anti-evil-maid.html

Building
=========

make all

This should build rpms and put them into rpm/x86_64/ subdir.

Building has only been tested on a x86_64 systems.

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

The instructions below assume Qubes OS or regular Fedora.

1) Enable TPM in BIOS.

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) Start the TrouSerS daemon (this should also load tpm driver into kernel):

# /etc/init.d/tcsd start

... or (in case of systems that use systemd):

# systemctl start tcsd

c) Verify the kernel support for TPM:

# find /sys/devices -name pcrs
# cat <path_to_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.

3) Take ownership of your TPM. This, among other things, would generate
the TPM SRK key used for sealing process:

# tpm_takeownership -y -z

NOTE: some users might want to use a non-default password for the SRK key (see the discussion in the article referenced above) -- in that case you SHOULD NOT pass the '-z' argument to tpm_takeownership, and also you SHOULD pass an additional argument to kernel (see point 4.c below).
NOTE: if your tpm has already been owned in the past, you can reset it by running tpm_clear -z, rebooting and resetting TPM in the BIOS (eg: TPM Authentication Reset).

4) Setup Anti Evil Maid

a) Anti Evil Maid packages:

You should have installed the following packages to perform the setup:
- anti-evil-maid-dracut
- anti-evil-maid

b) 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

You can then download the module and unzip it. All the modules can be downloaded from:
https://secure-software.intel.com/en-us/protected-download/267276/183305

Finally, you should retrieve the BIN file inside /boot in dom0. Eg: run from dom0 
$ 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) Find a USB stick, create a boot partition, set bootable flag, don't
format with any fs. Use fdisk or parted.

NOTE: when using a GPT partition table (rather than msdos), then you should
create an additional BIOS boot partition, where the rest of the GRUB code will
be kept -- please see this page for more info:
http://www.gnu.org/software/grub/manual/html_node/BIOS-installation.html

c) Set optional AEM additional flags: edit /etc/default/grub and add there (including the "export" word):

export GRUB_CMDLINE_AEM_FLAGS="flags"

Available flags (multiple flags can be separated by spaces):
 - rd.antievilmaid.asksrkpass: in case you decided to use a non-default
    password for the SRK key
 - rd.antievilmaid.png_secret: in case you plan to use a png sealed secret
 - rd.antievilmaid.dontforcestickremoval: in case if you don't want to remove
    the AEM stick during system startup (it is generally bad idea to use this
    flag, but can be useful in some unusal setups)

d) Install Anti Evil Maid on the stick. Use /usr/lib/antievilmaid/antievilmaid_install.

Ensure that none of your programs keep open files within /boot, as otherwise it won't be possible to smoothly unmount the /boot.

E.g. assuming your stick is /dev/sdc, boot partition is the 1st one, and
your existing boot files (images, grub conf) are available at /boot:

# /usr/lib/antievilmaid/antievilmaid_install /dev/sdc 1 /boot

DEPRECATED: ensure that your (previous) /boot partition is not in the
/etc/fstab. This is especially important if you don't have /boot on your disk
(so you installed /boot on some removable disk right from the beginning, which
is a good idea, BTW). In case you forgot to remove /boot entry from /etc/fstab,
then your system boot will fail because antievilmaid requires you to remove the
booting stick before proceeding with further boot, as a special security
precaution, see:

http://git.qubes-os.org/?p=joanna/antievilmaid.git;a=commit;h=5e8e879bfbe394a696b07479ae731422f553e28e

NOTE: it might still beneficial to remove one's original (stored on local
harddisk) /boot partition from the fstab. This way whenever one upgrades the
system (dom0 in case of Qubes OS), and the update process tries to modify files
in the /boot, an error will occur, reminding the user that the AEM stick should
be inserted and mounted as /boot for the update. Otherwise the user should
manually resync the local /boot content (e.g. new kernel and xen images) with
the AEM /boot.

e) Reboot the system from the stick, Choose one of the entries called Qubes OS AEM boot...

f) If a chunk of your installed RAM seems to be missing after the reboot (which can be
checked by running "xl info" in dom0), add the following line to /etc/default/grub --

export GRUB_CMDLINE_TBOOT="min_ram=0x2000000"

-- and execute the previous two steps 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.

5) Seal secret passphrase

a) Mount the stick again:

# mount LABEL=antievilmaid /mnt/antievilmaid

b) Start the tcsd daemon again (see 2.b). Then seal your secret passphrase to the TPM to select PCR registers, e.g.:

# tpm_sealdata -z -o /mnt/antievilmaid/antievilmaid/sealed_secret.blob --pcr 17 --pcr 18 --pcr 19
My secret passphrase<ENTER>
<CTRL+d> (twice if needed)

Notes:
Leave out the '-z' argument again if you used an SRK password in step 3.
Add '< my-secret-image.png' at the end of the command above if you want to use a png file as a secret (i.e. if you passed "rd.antievilmaid.png_secret" to kernel). The png file will be displayed as an icon next to the passprase prompt.

TCG spec defines the following PCRs that you might want to seal to:

PCR 0-3: BIOS, Option ROMs, Platform Config
PCR 4  : MBR (Grub stage1)
PCR 5-7: OEM-specific, probably safe to skip
PCR 8,9: Trusted GRUB1 stage2
PCR 12 : Trusted GRUB1 args (xen, kernel args)
PCR 14 : The actual files loaded by Trusted GRUB1 (xen, kernel, initrd)
PCR 17-19: TBoot Dynamic Root of Trust Measurement (DRTM)

c) Unmount the stick, reboot your system.

Now, every time you boot your system (from your Anti Evil Maid stick)
you should see your secret passphrase displayed *before* the LUKS
disk encryption passphrase prompt.

System and kernel upgrades
===========================

1) Kernel upgrade

When performing a xen or kernel upgrade you should ensure that your Anti Evil Maid stick is mounted at /boot. This way the new kernel post install script should automatically add kernel and initramfs to your stick and update grub2/grub.cfg correctly.

After xen or kernel upgrade you would need to boot the new kernel and reseal secrets to the new PCR values (PCR17, 18 or 19 would now be different obviously) as it is explained in point 5 above.

2) BIOS/firmware upgrade

If you updated your BIOS or Option ROM firmware, you would need to reseal secrets to new PCR values (PCRs 0-4 would change). Again, this requires that you boot from the stick after the upgrade and reseal the secret like it was explained in point 5 above.

Attacks prevented and not-prevented
====================================

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


