]>
Commit | Line | Data |
---|---|---|
f163b202 SB |
1 | =head1 NAME |
2 | ||
5311e60e | 3 | swtpm - TPM Emulator for TPM 1.2 and 2.0 |
f163b202 SB |
4 | |
5 | =head1 SYNOPSIS | |
6 | ||
7 | B<swtpm socket [OPTIONS]> | |
8 | ||
29cfd0a4 SB |
9 | B<swtpm chardev [OPTIONS]> |
10 | ||
78c5f924 SB |
11 | B<swtpm cuse [OPTIONS]> |
12 | ||
f163b202 SB |
13 | =head1 DESCRIPTION |
14 | ||
15 | B<swtpm> implements a TPM software emulator built on libtpms. | |
29cfd0a4 | 16 | It provides access to TPM functionality over a TCP/IP socket interface |
78c5f924 SB |
17 | or it can listend for commands on a character device, or create a CUSE |
18 | (character device in userspace) interface for receiving of TPM commands. | |
f163b202 SB |
19 | |
20 | Unless corresponding command line parameters are used, the | |
29cfd0a4 | 21 | B<swtpm> socket version requires that the environment variable I<TPM_PORT> |
f163b202 SB |
22 | be set to the TCP/IP port the process is supposed to listen on for TPM |
23 | request messages. | |
24 | ||
bc525ccd | 25 | Similarly, the environment variable I<TPM_PATH> can be set and |
f163b202 | 26 | contain the name of a directory where the TPM can store its persistent |
bc525ccd | 27 | state into. |
f163b202 | 28 | |
29cfd0a4 | 29 | The B<swtpm> process can be gracefully terminated by sending a |
f163b202 SB |
30 | I<SIGTERM> signal to it. |
31 | ||
78c5f924 SB |
32 | The B<swtpm> cuse version requires root rights to start the TPM. |
33 | ||
29cfd0a4 SB |
34 | =head1 Options for socket interface |
35 | ||
f163b202 SB |
36 | The following options are supported if the I<socket> interface is chosen: |
37 | ||
38 | =over 4 | |
39 | ||
40 | =item B<-p|--port <port>> | |
41 | ||
42 | Use the given port rather than using the environment variable TPM_PORT. | |
43 | ||
29cfd0a4 SB |
44 | =item B<-t|--terminate> |
45 | ||
46 | Terminate the TPM after the client has closed the connection. | |
47 | ||
fb5256bf | 48 | =item B<--server [type=tcp][,port=E<lt>portE<gt>[,bindaddr=E<lt>addressE<gt> [,ifname=E<lt>ifnameE<gt>]]][,fd=E<lt>fdE<gt>][,disconnect]> |
7c0a033f SB |
49 | |
50 | Expect TCP connections on the given port; if a port is not provided a file descriptor | |
51 | must be passed with the fd parameter and the commands are read from this file | |
52 | descriptor then. | |
16eb0ff2 SB |
53 | If a port is provided the I<bind address> on which to listen for TCP connections |
54 | can be provided as well; the default bind address is 127.0.0.1. If a link | |
2bc601bb | 55 | local IPv6 address is provided, the name of the interface to bind to must be |
16eb0ff2 | 56 | provided with I<ifname>. |
7c0a033f SB |
57 | |
58 | This parameter enables a persistent connection by default unless the disconnect option | |
59 | is given. This parameter should be used rather than the -p and --fd options. | |
60 | ||
fb5256bf | 61 | =item B<--server type=unixio[,path=E<lt>pathE<gt>][,fd=E<lt>fdE<gt>] [,mode=E<lt>0...E<gt>][,uid=E<lt>uidE<gt>][,gid=E<lt>gidE<gt>]> |
73823529 | 62 | |
682fe581 | 63 | Expect UnixIO connections on the given path. If no path is provided, a file descriptor |
2bc601bb | 64 | must be passed instead. The mode parameter allows a user to set the file mode bits of the |
682fe581 | 65 | UnixIO path. The mode bits value must be given as an octal number starting with a '0'. |
f34e01a5 SB |
66 | The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. |
67 | This operation requires root privileges. | |
73823529 | 68 | |
29cfd0a4 SB |
69 | =back |
70 | ||
71 | ||
72 | =head1 Options for character device interface | |
73 | ||
78c5f924 | 74 | The following options are supported if the I<chardev> interface is chosen: |
29cfd0a4 SB |
75 | |
76 | =over 4 | |
77 | ||
78 | =item B<-c|--chardev <device path>> | |
79 | ||
80 | Use the given device to listen for TPM commands and send response on. | |
81 | ||
ee8b6c2d SB |
82 | =item B<--vtpm-proxy> |
83 | ||
84 | Create a Linux vTPM proxy device instance and read TPM commands from its | |
85 | backend device. | |
86 | ||
29cfd0a4 SB |
87 | =back |
88 | ||
89 | ||
78c5f924 | 90 | =head1 Options for the CUSE interface |
29cfd0a4 | 91 | |
78c5f924 | 92 | The following options are supported if the I<cuse> interface is chosen: |
29cfd0a4 SB |
93 | |
94 | =over 4 | |
95 | ||
78c5f924 | 96 | =item B<-n|--name <NAME>> |
f163b202 | 97 | |
78c5f924 SB |
98 | The TPM will use a device with the given name. A device with the given name |
99 | will be created in /dev. This is a mandatory option. | |
100 | ||
101 | =item B<-M|--maj <MAJOR>> | |
102 | ||
103 | Create the device with the given major number. | |
104 | ||
105 | =item B<-m|--min <MINOR>> | |
106 | ||
107 | Create the device with the given minor number. | |
108 | ||
78c5f924 SB |
109 | =back |
110 | ||
111 | ||
112 | =head1 Options for socket and character device interfaces: | |
113 | ||
114 | The following options are supported by the socket and character device interfaces: | |
115 | ||
116 | =over 4 | |
f163b202 SB |
117 | |
118 | =item B<-f|--fd <fd>> | |
119 | ||
29cfd0a4 SB |
120 | Use the given socket file descriptor or character device file descriptor |
121 | for receiving TPM commands and sending responses. | |
122 | For the socket interface, this option automatically assumes -t. | |
f163b202 | 123 | |
78c5f924 SB |
124 | =item B<-d|--daemon> |
125 | ||
126 | Daemonize the process. | |
127 | ||
fb5256bf | 128 | =item B<--ctrl type=[unixio|tcp][,path=E<lt>pathE<gt>] [,port=E<lt>portE<gt>[,bindaddr=E<lt>addressE<gt>[,ifname=E<lt>ifnameE<gt>]]] [,fd=E<lt>filedescriptorE<gt>|clientfd=E<lt>filedescriptorE<gt>] [,mode=E<lt>0...E<gt>][,uid=E<lt>uidE<gt>][,gid=E<lt>gidE<gt>] > |
9ddc6998 SB |
129 | |
130 | This option adds a control channel to the TPM. The control channel can either use a UnixIO socket with | |
131 | a given I<path> or I<filedescriptor> or it can use a TCP socket on the given I<port> or I<filedescriptor>. | |
16eb0ff2 SB |
132 | If a port is provided the I<bind address> on which to listen for TCP connections |
133 | can be provided as well; the default bind address is 127.0.0.1. If a link | |
2bc601bb | 134 | local IPv6 address is provided, the name of the interface to bind to must be |
16eb0ff2 | 135 | provided with I<ifname>. |
9ddc6998 | 136 | |
2bc601bb | 137 | The mode parameter allows a user to set the file mode bits of the UnixIO path. |
682fe581 | 138 | The mode bits value must be given as an octal number starting with a '0'. |
f34e01a5 SB |
139 | The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. |
140 | This operation requires root privileges. | |
682fe581 | 141 | |
9ddc6998 SB |
142 | The control channel enables out-of-band control of the TPM, such as resetting the TPM. |
143 | ||
78c5f924 SB |
144 | =back |
145 | ||
146 | ||
147 | =head1 Options for all interfaces | |
148 | ||
149 | The following options are support by all interfaces: | |
150 | ||
151 | =over 4 | |
152 | ||
b82eb7e7 | 153 | =item B<--tpmstate dir=E<lt>dirE<gt>[,mode=E<lt>0...E<gt>]|backend-uri=E<lt>uriE<gt>> |
78c5f924 SB |
154 | |
155 | Use the given path rather than using the environment variable TPM_PATH. | |
156 | ||
b82eb7e7 ET |
157 | If I<dir> is specified, the TPM state files will be written to the I<dir> with |
158 | the given file I<mode> bits. This value must be given as an octal number starting with a '0'. | |
640f1fab SB |
159 | The default value is 0640. |
160 | ||
b82eb7e7 | 161 | If I<backend-uri> is specified, the TPM state data will be stored to the URI. |
b129b8df SR |
162 | Currently I<backend-uri=dir://<path_to_dir>> and I<backend-uri=file://<path_to_dir>> |
163 | are available. For 'dir://', the URI should specify the path to the directory where | |
164 | files are stored. If I<path_to_dir> starts with a '/' then the path is interpreted | |
165 | as an absolute path, otherwise it is a path relative to the current directory. | |
166 | For 'file://', the URI should specify a single file or block device where TPM state | |
167 | will be stored. A blockdevice must exist already and be big enough to store all | |
168 | state. | |
b82eb7e7 | 169 | |
fbc596ab SB |
170 | =item B<--tpm2> |
171 | ||
172 | Choose TPM 2 functionality; by default a TPM 1.2 is chosen. | |
173 | ||
fb5256bf | 174 | =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 |
175 | |
176 | Enable logging to a file given its file descriptor or its path. Use '-' for path to | |
177 | suppress the logging. | |
178 | ||
2bc601bb | 179 | The level parameter allows a user to choose the level of logging. Starting at log |
e8b5115f SB |
180 | level 5, libtpms debug logging is activated. |
181 | ||
93f4a389 SB |
182 | All logged lines will be prefixed with prefix. By default no prefix is prepended. |
183 | ||
3760c342 SB |
184 | If I<truncate> is passed, the log file will be truncated. |
185 | ||
a2f81ea2 | 186 | =item B<--locality reject-locality-4[,allow-set-locality]> |
4a565414 SB |
187 | |
188 | The I<reject-locality-4> parameter will cause TPM error messages to be | |
189 | returned for requests to set the TPM into locality 4. | |
190 | ||
a2f81ea2 SB |
191 | The I<allow-set-locality> parameter allows the swtpm to receive |
192 | TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux | |
193 | VTPM proxy driver access is enabled by file descriptor passing. | |
194 | This option is implied by the I<--vtpm-proxy> option and therefore need not | |
2bc601bb | 195 | be explicitly set if this option is passed. In all other cases care should be |
a2f81ea2 SB |
196 | taken as to who can send the TPM/TPM2_SetLocality command. |
197 | ||
fb5256bf | 198 | =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 |
199 | |
200 | Enable encryption of the state files of the TPM. The keyfile must contain | |
68a5b241 | 201 | an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are |
f163b202 SB |
202 | supported. |
203 | ||
68a5b241 SB |
204 | The key may be in binary format, in which case the file size must be 16 or |
205 | 32 bytes. If the key is in hex format (default), the key may consist of 32 | |
206 | or 64 hex digits starting with an optional '0x'. | |
f163b202 SB |
207 | |
208 | The I<mode> parameter indicates which block chaining mode is to be used. | |
68a5b241 SB |
209 | Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
210 | The encrypted data is integrity protected using encrypt-then-mac. | |
f163b202 SB |
211 | |
212 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
213 | has been read. | |
214 | ||
fb5256bf | 215 | =item B<--key pwdfile=E<lt>passphrase fileE<gt>|pwdfd=E<lt>fdE<gt> [,mode=aes-cbc|aes-256-cbc][remove[=true|false]][,kdf=sha512|pbkdf2]> |
f163b202 | 216 | |
2bc601bb | 217 | This variant of the key parameter allows a user to provide a passphrase in a file. |
a39f098f SB |
218 | The file is read and a key is derived from it using either a SHA512 hash |
219 | or PBKDF2. By default PBKDF2 is used. | |
f163b202 | 220 | |
fb5256bf | 221 | =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]]> |
84259c17 SB |
222 | |
223 | The availability of a migration key ensures that the state of the TPM | |
224 | will not be revealed in unencrypted form when | |
2bc601bb | 225 | the TPM state blobs are retrieved through the ioctl interface. |
84259c17 SB |
226 | The migration key is not used for encrypting TPM state written to files, |
227 | this is what the I<--key> parameter is used for. | |
228 | ||
229 | The migration key and the key used for encrypting the TPM state files may be the same. | |
230 | ||
231 | While the key for the TPM state files needs to stay with those files it encrypts, the | |
232 | migration key needs to stay with the TPM state blobs. If for example the state of the | |
233 | TPM is migrated between hosts in a data center, then the TPM migration key must be | |
234 | available at all the destinations, so in effect it may have to be a key shared across | |
235 | all machines in the datacenter. In contrast to that, the key used for encrypting the | |
236 | TPM state B<files> can be different for each TPM and need only be available | |
237 | on the host where the TPM state resides. | |
238 | ||
68a5b241 SB |
239 | The migration key enables the encryption of the TPM state blobs. |
240 | The keyfile must contain an AES key of supported size; 128 bit (16 bytes) | |
241 | and 256 bit (32 bytes) keys are supported. | |
84259c17 | 242 | |
68a5b241 SB |
243 | The key may be in binary format, in which case the file size must be 16 or |
244 | 32 bytes. If the key is in hex format (default), the key may consist of 32 | |
245 | or 64 hex digits starting with an optional '0x'. | |
84259c17 SB |
246 | |
247 | The I<mode> parameter indicates which block chaining mode is to be used. | |
68a5b241 SB |
248 | Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
249 | The encrypted data is integrity protected using encrypt-then-mac. | |
84259c17 SB |
250 | |
251 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
252 | has been read. | |
253 | ||
fb5256bf | 254 | =item B<--migration-key pwdfile=E<lt>passphrase fileE<gt>|pwdfd=E<lt>fdE<gt> [,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,pdf=sha512|pbkdf2]> |
a39f098f | 255 | |
2bc601bb | 256 | This variant of the key parameter allows a user to provide a passphrase in a file. |
a39f098f SB |
257 | The file is read and a key is derived from it using either a SHA512 hash |
258 | or PBKDF2. By default PBKDF2 is used. | |
84259c17 | 259 | |
db608775 | 260 | =item B<--pid file=E<lt>pidfileE<gt>|fd=E<lt>filedescriptorE<gt>> |
b2151737 | 261 | |
2bc601bb | 262 | This options allows a user to set the name of file where the process ID (pid) of the TPM |
db608775 SB |
263 | will be written into. It is also possible to pass a file descriptor to a file that |
264 | has been opened for writing. | |
b2151737 | 265 | |
bb420d74 SB |
266 | =item B<-r|--runas E<lt>ownerE<gt>> |
267 | ||
268 | Switch to the given user. This option can only be used when swtpm is started as root. | |
269 | ||
08e619ad | 270 | =item B<--seccomp action=none|log|kill> (since v0.2) |
9cd723d8 | 271 | |
2bc601bb | 272 | This option allows a user to select the action to take by the seccomp profile when |
9cd723d8 SB |
273 | a syscall is executed that is not allowed. The default is I<kill>. To disable |
274 | the seccomp profile, choose I<none>. The I<log> action logs offending syscalls. | |
275 | The I<log> action is only available if libseccomp supports logging. | |
276 | ||
277 | This option is only available on Linux and only if swtpm was compiled with | |
278 | libseccomp support. | |
279 | ||
ab40d27a SB |
280 | =item B<--flags [not-need-init] [,startup-clear|startup-state|startup-deactivated|startup-none]> |
281 | ||
282 | The I<not-need-init> flag enables the TPM to accept TPM commands right after | |
283 | start without requiring an INIT to be sent to it through the command channel | |
284 | (see the '-i' option of swtpm_ioctl). | |
285 | ||
286 | The I<startup> options cause a TPM_Startup or TPM2_Startup command to | |
287 | automatically be sent. The I<startup-deactivated> option is only valid for | |
288 | a TPM 1.2. These options imply I<not-need-init>, except for the | |
289 | I<startup-none> option, which results in no command being sent. | |
290 | ||
291 | If I<--vtpm-proxy> is used, I<startup-clear> is automatically chosen but | |
292 | this can be changed with this option. | |
293 | ||
14ae05b1 SB |
294 | =item B<--print-capabilities> (since v0.2) |
295 | ||
296 | Print capabilities that were added to swtpm after version 0.1. The output | |
297 | may contain the following: | |
298 | ||
299 | { | |
300 | "type": "swtpm", | |
301 | "features": [ | |
55404e26 MAL |
302 | "tpm-1.2", |
303 | "tpm-2.0", | |
14ae05b1 SB |
304 | "cmdarg-seccomp", |
305 | "cmdarg-key-fd", | |
306 | "cmdarg-pwd-fd", | |
e6cbc55d | 307 | "cmdarg-print-states", |
86931b4f | 308 | "nvram-backend-dir", |
0716f994 | 309 | "nvram-backend-file", |
14ae05b1 | 310 | "tpm-send-command-header", |
c6b52d18 SB |
311 | "flags-opt-startup", |
312 | "rsa-keysize-1024", | |
313 | "rsa-keysize-2048", | |
314 | "rsa-keysize-3072" | |
55404e26 MAL |
315 | ], |
316 | "version": "0.7.0" | |
14ae05b1 SB |
317 | } |
318 | ||
55404e26 MAL |
319 | The version field is available since 0.7. |
320 | ||
14ae05b1 SB |
321 | The meaning of the feature verbs is as follows: |
322 | ||
323 | =over 4 | |
324 | ||
55404e26 MAL |
325 | =item B<tpm-1.2> |
326 | ||
327 | TPM 1.2 emulation is supported (libtpms is compiled with 1.2 support). | |
328 | ||
329 | Since 0.7 | |
330 | ||
331 | ==item B<tpm-2.0> | |
332 | ||
333 | TPM 2 emulation is supported (libtpms is compiled with 2.0 support). | |
334 | ||
335 | (the I<--tpm2> option is supported) | |
336 | ||
337 | Since 0.7 | |
338 | ||
14ae05b1 SB |
339 | =item B<cmdarg-seccomp> |
340 | ||
341 | The I<--seccomp> option is supported. | |
342 | ||
343 | =item B<cmdarg-key-fd> | |
344 | ||
345 | The I<--key> option supports the I<fd=> parameter. | |
346 | ||
347 | =item B<cmdarg-pwd-fd> | |
348 | ||
349 | The I<--key> option supports the I<pwdfd=> parameter. | |
350 | ||
e6cbc55d SB |
351 | =item B<cmdarg-print-states> |
352 | ||
353 | The I<--print-states> option is supported. | |
354 | ||
86931b4f ET |
355 | =item B<nvram-backend-dir> |
356 | ||
225d7009 SB |
357 | The I<--tpmstate> option supports the I<backend-uri=dir://...> |
358 | parameter. | |
359 | ||
360 | =item B<nvram-backend-file> | |
361 | ||
362 | The I<--tpmstate> option supports the I<backend-uri=file://...> | |
363 | parameter. | |
86931b4f | 364 | |
14ae05b1 SB |
365 | =item B<tpm-send-command-header> |
366 | ||
367 | The TPM 2 commands may be prefixed by a header that carries a 4-byte | |
368 | command, 1 byte for locality, and 4-byte TPM 2 command length indicator. | |
369 | The TPM 2 will respond by preprending a 4-byte response indicator and a | |
370 | 4-byte trailer. All data is sent in big endian format. | |
371 | ||
041a70e7 SB |
372 | =item B<flags-opt-startup> |
373 | ||
374 | The I<--flags> option supports the I<startup-...> options. | |
375 | ||
c6b52d18 SB |
376 | =item B<rsa-keysize-2048> |
377 | ||
378 | The TPM 2 supports the shown RSA key sizes. If none of the | |
379 | rsa-keysize verbs is shown then only RSA 2048 bit keys are supported. | |
380 | ||
14ae05b1 SB |
381 | =back |
382 | ||
e6cbc55d SB |
383 | =item B<--print-states> |
384 | ||
385 | This option allows to print out the TPM 1.2 or TPM 2 state blobs | |
386 | that are currently stored in a storage backend. This option requires | |
387 | that the storage backend be specified using the I<--tpmstate> option | |
388 | and if TPM 2 state blobs are supposed to be shown, the I<--tpm2> | |
389 | option must be passed. | |
390 | ||
391 | The following shows the JSON output of this option. It indicates that | |
392 | the 'permall' and 'volatile' states are available. | |
393 | ||
394 | { | |
395 | "type": "swtpm", | |
396 | "states": [ | |
397 | { | |
398 | "name": "permall", | |
399 | "size": 6013 | |
400 | }, { | |
401 | "name": "volatile", | |
402 | "size": 1087 | |
403 | } | |
404 | ] | |
405 | } | |
406 | ||
f163b202 SB |
407 | =item B<-h|--help> |
408 | ||
409 | Display usage info. | |
410 | ||
411 | =back | |
412 | ||
413 | ||
414 | =head1 SEE ALSO | |
415 | ||
78c5f924 | 416 | B<swtpm_bios>, B<swtpm_cuse> |