Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Store and restore a persistent passphrase with TPM 2.0
Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Type||Name||Latest commit message||Commit time|
|Failed to load latest commit information.|
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-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-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-tss 1.3.0 - The TCG TPM2 Software Stack https://github.com/tpm2-software/tpm2-tss tpm2-abrmd 1.2.0 - The resource manager https://github.com/tpm2-software/tpm2-abrmd.git tpm2-tools 1.3.1 - The TPM 2.0 tools https://github.com/tpm2-software/tpm2-tools meta-secure-core - A practical full-disk-encryption implementation with TPM 2.0 based on Pulsar Linux https://github.com/jiazhang0/meta-secure-core