diff --git a/docs/tpm.md b/docs/tpm.md new file mode 100644 index 000000000..aadd07d81 --- /dev/null +++ b/docs/tpm.md @@ -0,0 +1,122 @@ +# TPM +Tpm in Cloud-Hypervisor is emulated using `swtpm` as the backend. [swtpm](https://github.com/stefanberger/swtpm) is the link to swtpm project. + +Current implementation only supports TPM `2.0` version. At the moment only +`CRB Interface` is implemented. This interface is described in +[TCG PC Client Platform TPM Profile Specification for TPM 2.0, Revision 01.05 v4](https://trustedcomputinggroup.org/wp-content/uploads/PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.pdf). + + +## Usage +`--tpm`, an optional argument, can be passed to enable tpm device. +This argument takes an UNIX domain Socket as a `socket` value. + +_Example_ + +An Example invocation with `--tpm` argument: + +``` + ./cloud-hypervisor/target/release/cloud-hypervisor \ + --kernel ./hypervisor-fw \ + --disk path=focal-server-cloudimg-amd64.raw \ + --cpus boot=4 \ + --memory size=1024M \ + --net "tap=,mac=,ip=,mask=" \ + --tpm socket="/var/run/swtpm.socket" +``` + +## swtpm +Before invoking cloud-hypervisor with `--tpm` argument, a `swtpm` +process should be started to listen at the input socket. Below is an +example invocation of swtpm process. + +``` +swtpm socket --tmpstate dir=/var/run/swtpm \ + --ctrl type=unixio,path="/var/run/swtpm.socket" \ + --flags startup-clear \ + --tpm2 +``` + +## Guest +After starting a guest with the above commands, ensure below listed modules are +loaded in the guest: + +``` +# lsmod | grep tpm +tpm_crb 20480 0 +tpm 81920 1 tpm_crb +``` + +Below is the IO Memory map configured in the guest: + +``` +# cat /proc/iomem | grep MSFT +fed40000-fed40fff : MSFT0101:00 + fed40000-fed40fff : MSFT0101:00 +``` +Below are the devices created in the guest: + +``` +# ls /dev/tpm* +/dev/tpm0 /dev/tpmrm0 +``` + + +## Testing + +Inside the guest install `tpm2-tools` package. This package provides some +commands to run against TPM that supports 2.0 version. + +_Examples_ +``` +// Run Self Test +# tpm2_selftest -f +# echo $? +0 + + +# echo "hello" > input.txt +// this command generates hash of the input file using all the algos supported by TPM + +# tpm2_pcrevent input.txt +sha1: f572d396fae9206628714fb2ce00f72e94f2258f +sha256: 5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 +sha384: 1d0f284efe3edea4b9ca3bd514fa134b17eae361ccc7a1eefeff801b9bd6604e01f21f6bf249ef030599f0c +218f2ba8c +sha512: e7c22b994c59d9cf2b48e549b1e24666636045930d3da7c1acb299d1c3b7f931f94aae41edda2c2b207a36e +10f8bcb8d45223e54878f5b316e7ce3b6bc019629 + +// verify one of the hashes +# sha256sum input.txt +5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03 input.txt +``` + +### Bundled Functional Test + +Build time dependencies for `tpm2-tss` are captured in [INSTALL](https://github.com/tpm2-software/tpm2-tss/blob/master/INSTALL.md). + +``` +# git clone https://github.com/tpm2-software/tpm2-tss.git +# cd tpm2-tss +# ./configure --enable-integration --with-devicetests="mandatory,optional" --with-device=/dev/tpm0 +# sudo make check-device +. +. +. +. +============================================================================ +Testsuite summary for tpm2-tss 3.2.0-74-ge03617d9 +============================================================================ +# TOTAL: 154 +# PASS: 88 +# SKIP: 7 +# XFAIL: 0 +# FAIL: 59 +# XPASS: 0 +# ERROR: 0 +============================================================================ +See ./test-suite.log +Please report to https://github.com/tpm2-software/tpm2-tss/issues +============================================================================ +``` +The same set of failures are noticed while running these tests on `Qemu` with +its TPM implementation.