Cryptfs-TPM2
============

This project provides with an implementation used to create, persist,
evict a passphrase for full-disk-encryption with TPM 2.0.

The passphrase and its associated primary key may be created by RNG engine
in TPM or manually typed. In order to avoid saving the context file on the
untrustworthy media, the created passphrase and primary key are always
persistent in TPM.

Currently, the resulting binaries consist of cryptfs-tpm2 and
libcryptfs-tpm2.so.

Build
-----
This package depends on TPM2.0-TSS and tpm2-abrmd. Download them (see the
section "Reference" for the download link) and run the script "bootstrap" to
compile the library, then switch to root directory of cryptfs-tpm2 and run
"make" to build cryptfs-tpm2.

Alternately, specifying the macros tpm2_tss_includedir, tpm2_tss_libdir
and tpm2_tabrmd_includedir to build cryptfs-tpm2 with TPM2.0-TSS and tpm2-abrmd
even though they were built but not installed. For example:

$ export TSS2_ROOT=<path_to_TPM2.0-TSS>
$ export TABRMD_ROOT=<path_to_tpm2-abrmd>
$ tpm2_tss_includedir=$TSS2_ROOT/include \
  tpm2_tss_libdir="$TSS2_ROOT/sysapi/.libs $TSS2_ROOT/tcti/.libs" \
  tpm2_tabrmd_includedir="$TABRMD_ROOT/include" \
  make

Note: define the macro "CROSS_COMPILE=" in command line if specifying cross
compilation.

Installation
------------
$ sudo make install
$ sudo ldconfig

Help
----
- For the available options and sub-commands:
# cryptfs-tpm2 -h

- For a sub-command:
# cryptfs-tpm2 help <subcmd>

Quick start
-----------
- Preparation
Clear TPM 2.0 device through setting the security jumper on the board or
running tpm2_takeownership -c. The latter is provided by tpm2.0-tools.

Note: cryptfs-tpm2 will create the primary key and passphrase in the owner
hierarchy and so always specify --owner-auth option to set the authorization
value for accessing owner hierarchy if required.

- Create the primary key and passphrase
The typical method is to create the primary key and passphrase by TPM 2.0.
# cryptfs-tpm2 seal all

Manually typed passphrase is also supported.
# cryptfs-tpm2 seal all -p <passphrase>

PCR (index 7) binding is more secure.
# cryptfs-tpm2 seal all -P <digest>
where <digest> may be "sha1" or "sha256" or anything else if supported by
TPM 2.0 device, or specify "auto" which will chooses the highest strength
digest algorithm as the preference.

Note: if the preferred PCR bank doesn't extend PCR index 7 ever, cryptfs-tpm2
will still choose a weaker PCR bank as long as its PCR index 7 was extended.
For example, assuming TPM device already enabled both SHA1 and SHA256 PCR
banks, and if PCR 7 in SHA256 PCR bank is not extended and PCR 7 in SHA1 PCR
bank is by BIOS or bootloader, the SHA1 PCR bank is chosen.

- Retrieve the passphrase
# cryptfs-tpm2 unseal passphrase -o <saved_passphrase>
or
# cryptfs-tpm2 unseal passphrase -P <digest> -o <saved_passphrase>
if PCR binding is used.

- Evict the primary key and passphrase
# cryptfs-tpm2 evict all

CAUTION: beware of the permanent loss of them and assoicated data
encryption if you do this.

Authentication
--------------
Access an object in TPM requires an authentication check. The table below
records the required secret info for the operation to an object.

                      owner-auth  primary-key-secret  passphrase-secret
seal   (primary key)  Y           N                   N
seal   (passphrase)   Y           Y                   N
unseal (passphrase)   N           N                   Y
evict  (passphrase)   Y           N                   N

Known issues
------------

Validation
----------
The following TPM 2.0 devices are validated with cryptfs-tpm2.

dTPM:
- Infineon TPM SLB 9665
- STMicroelectronics ST33TPHF2ESPI

fTPM:
- Intel fTPM on Leaf Hill (rev C)

sTPM:
- IBM Software TPM
http://ibmswtpm.sourceforge.net/ibmswtpm2.html

Reference
---------
TPM2.0-TSS - The TCG TPM2 Software Stack (Use 1.x branch)
https://github.com/01org/TPM2.0-TSS

tpm2-abrmd - The resource manager
https://github.com/01org/tpm2-abrmd.git

tpm2.0-tools - The TPM 2.0 tools
https://github.com/01org/tpm2.0-tools

meta-secure-env - A practical full-disk-encryption implementation with TPM 2.0
                  based on Pulsar Linux
https://github.com/WindRiver-OpenSourceLabs/meta-secure-env