1 files changed, 64 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 000000000000..5ad0e35d54e4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+mkinitcpio TPM2 hook
+====================
+
+This mkinitcpio hook allows for an encrypted root device to use a key sealed by
+a TPM 2.0. It should be placed immediately before the `encrypt` hook in
+`/etc/mkinitcpio.conf`.
+
+    HOOKS="base udev ... block tpm2 encrypt filesystems 
+
+The `tpm2` hook attempts to "unseal" a LUKS keyfile previously sealed by the
+TPM. The sealed files must reside on an unencrypted filesystem available to the
+kernel at boot or may be stored in TPM non-volatile memory (NVRAM). For example,
+assuming your unencrypted keyfile is at `/root/mykey` and a primary TPM key has
+been persisted to `0x81000001`:
+
+    # tpm2_createpolicy -P -L sha1:0,2,4,7 -f pcr.pol -T device:/dev/tpmrm0
+    # tpm2_create -H 0x81000001 -g sha256 -G keyedhash -A 0x492 -I /root/mykey \
+      -L pcr.pol -r /boot/mykey.priv -u /boot/mykey.pub -T device:/dev/tpmrm0
+
+After generating a TPM-sealed key, both `tpmkey` and `tpmpcr` should be specified
+on the kernel command line.
+
+The `tpmkey` parameter has several formats:
+
+    tpmkey=[device]:[path]:[handle]
+    tpmkey=[device]:[publicpath]:[privatepath]:[handle]
+    tpmkey=nvram:[index]
+    tpmkey=nvram:[index]:[offset]:[size]
+
+Where `[device]` represents the raw block device on which the key exists,
+`[path]` is the absolute base path of the sealed files within the device, and
+`[handle]` is the TPM handle of the key's parent object. If only `[path]` is
+specified, '.pub' and '.priv' will be appended to the path to locate the public
+and private files, respectively. The absolute `[publicpath]` and `[privatepath]`
+can be specified separately if needed. For example, if `/dev/sda1` is an EFI
+partition mounted at `/boot`:
+
+    tpmkey=/dev/sda1:/mykey:0x81000001
+
+Setting `[device]` to 'nvram' indicates that the key is stored in TPM NVRAM. In
+this case `[index]` is the NVRAM area index, `[offset]` is the offset of the key
+in bytes and `[size]` is the size of the key in bytes.
+
+The `tpmpcr` parameter should hold the TPM2 PCR bank specification that will
+unlock the sealed key. Multiple specs can be separated by a '|' and key
+decryption will be attempted with each set of banks.
+
+You may also need to add the `vfat` file system driver to the `MODULES` array:
+
+    MODULES=(vfat)
+
+Finally, rebuild the initramfs:
+
+    # mkinitcpio -p linux
+
+During boot, the hook will initialize the TPM and attempt to unseal the key. If
+the key is successfully unsealed, it will be passed to the `encrypt` hook to
+perform the actual decryption of the root file system.
+
+Depending on the PCR banks to which the sealed key is bound, system changes such
+as kernel updates or firmware adjustments may prevent the key from being
+unsealed. If this happens, the disk must be manually unlocked with a passphrase
+and a new sealed key file needs to be generated. For this reason, it is CRUCIAL
+to add a separate "recovery" passphrase to the LUKS keys.