-
Notifications
You must be signed in to change notification settings - Fork 13
/
README
138 lines (106 loc) · 4.27 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
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
Release
------------
$ ./release.sh
The RPM package will be built into the `release` dir under current dir.
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 2.0.0 - The TCG TPM2 Software Stack
https://github.com/tpm2-software/tpm2-tss
tpm2-abrmd 2.0.1 - The resource manager
https://github.com/tpm2-software/tpm2-abrmd.git
tpm2-tools 3.1.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