]>
Commit | Line | Data |
---|---|---|
f163b202 SB |
1 | =head1 NAME |
2 | ||
5311e60e | 3 | swtpm - TPM Emulator for TPM 1.2 and 2.0 with a CUSE interface only |
f163b202 SB |
4 | |
5 | =head1 SYNOPSIS | |
6 | ||
7 | B<swtpm_cuse [OPTIONS]> | |
8 | ||
9 | =head1 DESCRIPTION | |
10 | ||
11 | B<swtpm_cuse> implements a TPM software emulator built on libtpms. | |
bc525ccd | 12 | It provides access to TPM functionality over a Linux CUSE |
f163b202 SB |
13 | (character device in user space) interface. |
14 | ||
f163b202 SB |
15 | The B<swtpm_ioctl> command should be used for a graceful shutdown |
16 | of the CUSE TPM. | |
17 | ||
18 | The following options are supported: | |
19 | ||
20 | =over 4 | |
21 | ||
22 | =item B<-h | --help> | |
23 | ||
24 | Display help screen. | |
25 | ||
bc525ccd SB |
26 | =item B<--tpmstate dir=E<lt>dirE<gt>> |
27 | ||
28 | This parameter allows to set the directory where the TPM will | |
29 | store its persistent state to. If this parameter is not set, | |
30 | the environment variable I<TPM_PATH> can be set instead. | |
31 | ||
f163b202 SB |
32 | =item B<-n E<lt>device nameE<gt> | --name=E<lt>device nameE<gt> (mandatory)> |
33 | ||
34 | The name of the character device to create. To create /dev/vtpm-200, the | |
35 | given device name must be vtpm-200. The character device will be created | |
36 | automatically and use unused major and minor numbers unless they | |
37 | are explicitly requested through options. | |
38 | ||
39 | =item B<-M E<lt>majorE<gt> | --maj=E<lt>majorE<gt>> | |
40 | ||
41 | The device major number to use; can be omitted. | |
42 | ||
43 | =item B<-m E<lt>minorE<gt> | --min=E<lt>minorE<gt>> | |
44 | ||
45 | The device minor number to use; can be omitted. | |
46 | ||
fbc596ab SB |
47 | =item B<--tpm2> |
48 | ||
49 | Choose TPM 2 functionality; by default a TPM 1.2 is chosen. | |
50 | ||
f163b202 SB |
51 | =item B<-r E<lt>userE<gt> | --runas=E<lt>userE<gt>> |
52 | ||
53 | The user to switch to and drop privileges. | |
54 | ||
3760c342 | 55 | =item B<--log fd=E<lt>fdE<gt>|file=E<lt>pathE<gt>[,level=E<lt>nE<gt>]>[,prefix=E<lt>prefixE<gt>][,truncate] |
f163b202 SB |
56 | |
57 | Enable logging to a file given its file descriptor or its path. Use '-' for path to | |
58 | suppress the logging. | |
59 | ||
c7c657ec SB |
60 | The level parameter allows to choose the level of logging. Starting at log |
61 | level 5, libtpms debug logging is activated. | |
62 | ||
93f4a389 SB |
63 | All logged lines will be prefixed with prefix. By default no prefix is prepended. |
64 | ||
3760c342 SB |
65 | If I<truncate> is passed, the log file will be truncated. |
66 | ||
a2f81ea2 | 67 | =item B<--locality [reject-locality-4][,allow-set-locality]> |
4a565414 SB |
68 | |
69 | The I<reject-locality-4> parameter will cause TPM error messages to be | |
70 | returned for requests to set the TPM into locality 4. | |
71 | ||
a2f81ea2 SB |
72 | The I<allow-set-locality> parameter allows the swtpm to receive |
73 | TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux | |
74 | VTPM proxy driver access is enabled by file descriptor passing. | |
75 | This option is implied by the I<--vtpm-proxy> option and therefore need not | |
76 | be explicity set if this option is passed. In all other cases care should be | |
77 | taken as to who can send the TPM/TPM2_SetLocality command. | |
78 | ||
87448aad | 79 | =item B<--key file=E<lt>keyfileE<gt>|fd=E<lt>fdE<gt>[,format=E<lt>hex|binaryE<gt>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]> |
f163b202 SB |
80 | |
81 | Enable encryption of the state files of the TPM. The keyfile must contain | |
68a5b241 | 82 | an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are |
f163b202 SB |
83 | supported. |
84 | ||
68a5b241 SB |
85 | The key may be in binary format, in which case the file size must be 16 or |
86 | 32 bytes. If the key is in hex format (default), the key may consist of 32 | |
87 | or 64 hex digits starting with an optional '0x'. | |
f163b202 SB |
88 | |
89 | The I<mode> parameter indicates which block chaining mode is to be used. | |
68a5b241 SB |
90 | Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
91 | The encrypted data is integrity protected using encrypt-then-mac. | |
f163b202 SB |
92 | |
93 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
94 | has been read. | |
95 | ||
68a5b241 | 96 | =item B<--key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]> |
f163b202 SB |
97 | |
98 | This variant of the key parameter allows to provide a passphrase in a file. | |
a39f098f SB |
99 | The file is read and a key is derived from it using either a SHA512 hash |
100 | or PBKDF2. By default PBKDF2 is used. | |
f163b202 | 101 | |
87448aad | 102 | =item B<--migration-key file=E<lt>keyfileE<gt>|fd=E<lt>fdE<gt>[,format=E<lt>hex|binaryE<gt>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]> |
1680c41d SB |
103 | |
104 | The availability of a migration key ensures that the state of the TPM | |
105 | will not be revealed in unencrypted form by the swtpm_cuse program when | |
106 | the TPM state blobs are retreived through the ioctl interface. | |
107 | The migration key is not used for encrypting TPM state written to files, | |
108 | this is what the <I>--key<I> parameter is used for. | |
109 | ||
110 | The migration key and the key used for encrypting the TPM state files may be the same. | |
111 | ||
112 | While the key for the TPM state files needs to stay with those files it encrypts, the | |
113 | migration key needs to stay with the TPM state blobs. If for example the state of the | |
114 | TPM is migrated between hosts in a data center, then the TPM migration key must be | |
115 | available at all the destinations, so in effect it may have to be a key shared across | |
116 | all machines in the datacenter. In contrast to that, the key used for encrypting the | |
117 | TPM state <B>files<B> can be different for each TPM and need only be available | |
118 | on the host where the TPM state resides. | |
119 | ||
68a5b241 SB |
120 | The migration key enables the encryption of the TPM state blobs. |
121 | The keyfile must contain an AES key of supported size; 128 bit (16 bytes) | |
122 | and 256 bit (32 bytes) keys are supported. | |
1680c41d | 123 | |
68a5b241 SB |
124 | The key may be in binary format, in which case the file size must be 16 or |
125 | 32 bytes. If the key is in hex format (default), the key may consist of 32 | |
126 | or 64 hex digits starting with an optional '0x'. | |
1680c41d SB |
127 | |
128 | The I<mode> parameter indicates which block chaining mode is to be used. | |
68a5b241 SB |
129 | Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
130 | The encrypted data is integrity protected using encrypt-then-mac. | |
1680c41d SB |
131 | |
132 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
133 | has been read. | |
134 | ||
68a5b241 | 135 | =item B<--migration-key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]> |
a39f098f SB |
136 | |
137 | This variant of the key parameter allows to provide a passphrase in a file. | |
138 | The file is read and a key is derived from it using either a SHA512 hash | |
139 | or PBKDF2. By default PBKDF2 is used. | |
1680c41d | 140 | |
db608775 | 141 | =item B<--pid file=E<lt>pidfileE<gt>>|fd=E<lt>filedescriptorE<gt>> |
b2151737 SB |
142 | |
143 | This options allows to set the name of file where the process ID (pid) of the CUSE TPM | |
db608775 SB |
144 | will be written into. The file will be written by the root user. It is also possible to |
145 | pass a file descriptor to a file that has been opened for writing. | |
b2151737 | 146 | |
9cd723d8 SB |
147 | =item B<--seccomp action=none|log|kill> |
148 | ||
149 | This option allows to select the action to take by the seccomp profile when | |
150 | a syscall is executed that is not allowed. The default is I<kill>. To disable | |
151 | the seccomp profile, choose I<none>. The I<log> action logs offending syscalls. | |
152 | The I<log> action is only available if libseccomp supports logging. | |
153 | ||
154 | This option is only available on Linux and only if swtpm was compiled with | |
155 | libseccomp support. | |
156 | ||
f163b202 SB |
157 | =back |
158 | ||
fbc596ab SB |
159 | =head1 EXAMPLES |
160 | ||
161 | To start the CUSE TPM and have it create the character device /dev/foo, | |
162 | use the following commands: | |
163 | ||
164 | =over 4 | |
165 | ||
166 | # ensure that previous swtpm_cuse using /dev/foo is gone | |
167 | ||
168 | swtpm_ioctl -s /dev/foo | |
169 | ||
170 | # Start the swtpm with TPM 2 functionality and make it accessible | |
171 | # through /dev/foo. Have the swtpm_cuse write the TPM's persistent | |
172 | # state into the given directory. | |
173 | ||
174 | export TPM_PATH=/tmp/foo | |
175 | mkdir -p $TPM_PATH | |
176 | ||
177 | swtpm_cuse -n foo --tpm2 | |
178 | ||
179 | # Send TPM_Init to the TPM; this is absolutely necessary | |
180 | ||
181 | swtpm_ioctl -i /dev/foo | |
182 | ||
183 | =back | |
f163b202 SB |
184 | |
185 | =head1 SEE ALSO | |
186 | ||
187 | B<swtpm_bios>, B<swtpm_ioctl> |