1swtpm(8)                                                              swtpm(8)
2
3
4

NAME

6       swtpm - TPM Emulator for TPM 1.2 and 2.0
7

SYNOPSIS

9       swtpm socket [OPTIONS]
10
11       swtpm chardev [OPTIONS]
12
13       swtpm cuse [OPTIONS]
14

DESCRIPTION

16       swtpm implements a TPM software emulator built on libtpms.  It provides
17       access to TPM functionality over a TCP/IP socket interface or it can
18       listend for commands on a character device, or create a CUSE (character
19       device in userspace) interface for receiving of TPM commands.
20
21       Unless corresponding command line parameters are used, the swtpm socket
22       version requires that the environment variable TPM_PORT be set to the
23       TCP/IP port the process is supposed to listen on for TPM request
24       messages.
25
26       Similarly, the environment variable TPM_PATH can be set and contain the
27       name of a directory where the TPM can store its persistent state into.
28
29       The swtpm process can be gracefully terminated by sending a SIGTERM
30       signal to it.
31
32       The swtpm cuse version requires root rights to start the TPM.
33

Options for socket interface

35       The following options are supported if the socket interface is chosen:
36
37       -p|--port <port>
38           Use the given port rather than using the environment variable
39           TPM_PORT.
40
41       -t|--terminate
42           Terminate the TPM after the client has closed the data channel
43           connection (TCP only).
44
45       --server [type=tcp][,port=<port>[,bindaddr=<address>
46       [,ifname=<ifname>]]][,fd=<fd>][,disconnect]
47           Expect TCP connections on the given port; if a port is not provided
48           a file descriptor must be passed with the fd parameter and the
49           commands are read from this file descriptor then.  If a port is
50           provided the bind address on which to listen for TCP connections
51           can be provided as well; the default bind address is 127.0.0.1. If
52           a link local IPv6 address is provided, the name of the interface to
53           bind to must be provided with ifname.
54
55           This parameter enables a persistent connection by default unless
56           the disconnect option is given. This parameter should be used
57           rather than the -p and --fd options.
58
59       --server type=unixio[,path=<path>][,fd=<fd>]
60       [,mode=<0...>][,uid=<uid>][,gid=<gid>]
61           Expect UnixIO connections on the given path. If no path is
62           provided, a file descriptor must be passed instead. The mode
63           parameter allows a user to set the file mode bits of the UnixIO
64           path. The mode bits value must be given as an octal number starting
65           with a '0'.  The default value is 0770. uid and gid set the
66           ownership of the UnixIO socket's path.  This operation requires
67           root privileges.
68

Options for character device interface

70       The following options are supported if the chardev interface is chosen:
71
72       -c|--chardev <device path>
73           Use the given device to listen for TPM commands and send response
74           on.
75
76       --vtpm-proxy
77           Create a Linux vTPM proxy device instance and read TPM commands
78           from its backend device.
79

Options for the CUSE interface

81       The following options are supported if the cuse interface is chosen:
82
83       -n|--name <NAME>
84           The TPM will use a device with the given name. A device with the
85           given name will be created in /dev. This is a mandatory option.
86
87       -M|--maj <MAJOR>
88           Create the device with the given major number.
89
90       -m|--min <MINOR>
91           Create the device with the given minor number.
92

Options for socket and character device interfaces:

94       The following options are supported by the socket and character device
95       interfaces:
96
97       -f|--fd <fd>
98           Use the given socket file descriptor or character device file
99           descriptor for receiving TPM commands and sending responses.  For
100           the socket interface, this option automatically assumes -t.
101
102       -d|--daemon
103           Daemonize the process.
104
105       --ctrl type=[unixio|tcp][,path=<path>]
106       [,port=<port>[,bindaddr=<address>[,ifname=<ifname>]]]
107       [,fd=<filedescriptor>|clientfd=<filedescriptor>]
108       [,mode=<0...>][,uid=<uid>][,gid=<gid>][,terminate]
109           This option adds a control channel to the TPM. The control channel
110           can either use a UnixIO socket with a given path or filedescriptor
111           or it can use a TCP socket on the given port or filedescriptor.  If
112           a port is provided the bind address on which to listen for TCP
113           connections can be provided as well; the default bind address is
114           127.0.0.1. If a link local IPv6 address is provided, the name of
115           the interface to bind to must be provided with ifname.
116
117           The mode parameter allows a user to set the file mode bits of the
118           UnixIO path.  The mode bits value must be given as an octal number
119           starting with a '0'.  The default value is 0770. uid and gid set
120           the ownership of the UnixIO socket's path.  This operation requires
121           root privileges.
122
123           The terminate parameter enables the automatic termination of swtpm
124           when the control channel connection has been lost. This is useful
125           in scenarios where the control channel connection is held
126           permanently, such as by QEMU, and swtpm should terminate upon
127           abnormal termination of the client that could not send a
128           CMD_SHUTDOWN via the control channel anymore.
129
130           The control channel enables out-of-band control of the TPM, such as
131           resetting the TPM.
132

Options for all interfaces

134       The following options are support by all interfaces:
135
136       --tpmstate dir=<dir>[,mode=<0...>]|backend-uri=<uri>
137           Use the given path rather than using the environment variable
138           TPM_PATH.
139
140           If dir is specified, the TPM state files will be written to the dir
141           with the given file mode bits. This value must be given as an octal
142           number starting with a '0'.  The default value is 0640.
143
144           If backend-uri is specified, the TPM state data will be stored to
145           the URI.  Currently backend-uri=dir://<path_to_dir> and
146           backend-uri=file://<path_to_dir> are available. For 'dir://', the
147           URI should specify the path to the directory where files are
148           stored. If path_to_dir starts with a '/' then the path is
149           interpreted as an absolute path, otherwise it is a path relative to
150           the current directory.  For 'file://', the URI should specify a
151           single file or block device where TPM state will be stored. A
152           blockdevice must exist already and be big enough to store all
153           state. (since v0.7)
154
155       --tpm2
156           Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
157
158       --log [fd=<fd>|file=<path>][,level=<n>] [,prefix=<prefix>][,truncate]
159           Enable logging to a file given its file descriptor or its path. Use
160           '-' for path to suppress the logging.
161
162           The level parameter allows a user to choose the level of logging.
163           Starting at log level 5, libtpms debug logging is activated.
164
165           All logged lines will be prefixed with prefix. By default no prefix
166           is prepended.
167
168           If truncate is passed, the log file will be truncated.
169
170       --locality reject-locality-4[,allow-set-locality]
171           The reject-locality-4 parameter will cause TPM error messages to be
172           returned for requests to set the TPM into locality 4.
173
174           The allow-set-locality parameter allows the swtpm to receive
175           TPM/TPM2_SetLocality commands. This is parameter is useful if the
176           Linux VTPM proxy driver access is enabled by file descriptor
177           passing.  This option is implied by the --vtpm-proxy option and
178           therefore need not be explicitly set if this option is passed. In
179           all other cases care should be taken as to who can send the
180           TPM/TPM2_SetLocality command.
181
182       --key file=<keyfile>|fd=<fd>
183       [,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc],
184       [remove[=true|false]]
185           Enable encryption of the state files of the TPM. The keyfile must
186           contain an AES key of supported size; 128 bit (16 bytes) and 256
187           bit (32 bytes) keys are supported.
188
189           The key may be in binary format, in which case the file size must
190           be 16 or 32 bytes. If the key is in hex format (default), the key
191           may consist of 32 or 64 hex digits starting with an optional '0x'.
192
193           The mode parameter indicates which block chaining mode is to be
194           used.  Currently aes-cbc (aes-128-cbc) and aes-256-cbc are
195           supported.  The encrypted data is integrity protected using
196           encrypt-then-mac.
197
198           The remove parameter will attempt to remove the given keyfile once
199           the key has been read.
200
201       --key pwdfile=<passphrase file>|pwdfd=<fd>
202       [,mode=aes-cbc|aes-256-cbc][remove[=true|false]][,kdf=sha512|pbkdf2]
203           This variant of the key parameter allows a user to provide a
204           passphrase in a file.  The file is read and a key is derived from
205           it using either a SHA512 hash or PBKDF2. By default PBKDF2 is used.
206
207       --migration-key file=<keyfile>|fd=<fd>
208       [,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc]
209       [,remove[=true|false]]
210           The availability of a migration key ensures that the state of the
211           TPM will not be revealed in unencrypted form when the TPM state
212           blobs are retrieved through the ioctl interface.  The migration key
213           is not used for encrypting TPM state written to files, this is what
214           the --key parameter is used for.
215
216           The migration key and the key used for encrypting the TPM state
217           files may be the same.
218
219           While the key for the TPM state files needs to stay with those
220           files it encrypts, the migration key needs to stay with the TPM
221           state blobs. If for example the state of the TPM is migrated
222           between hosts in a data center, then the TPM migration key must be
223           available at all the destinations, so in effect it may have to be a
224           key shared across all machines in the datacenter. In contrast to
225           that, the key used for encrypting the TPM state files can be
226           different for each TPM and need only be available on the host where
227           the TPM state resides.
228
229           The migration key enables the encryption of the TPM state blobs.
230           The keyfile must contain an AES key of supported size; 128 bit (16
231           bytes) and 256 bit (32 bytes) keys are supported.
232
233           The key may be in binary format, in which case the file size must
234           be 16 or 32 bytes. If the key is in hex format (default), the key
235           may consist of 32 or 64 hex digits starting with an optional '0x'.
236
237           The mode parameter indicates which block chaining mode is to be
238           used.  Currently aes-cbc (aes-128-cbc) and aes-256-cbc are
239           supported.  The encrypted data is integrity protected using
240           encrypt-then-mac.
241
242           The remove parameter will attempt to remove the given keyfile once
243           the key has been read.
244
245       --migration-key pwdfile=<passphrase file>|pwdfd=<fd>
246       [,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,pdf=sha512|pbkdf2]
247           This variant of the key parameter allows a user to provide a
248           passphrase in a file.  The file is read and a key is derived from
249           it using either a SHA512 hash or PBKDF2. By default PBKDF2 is used.
250
251       --pid file=<pidfile>|fd=<filedescriptor>
252           This options allows a user to set the name of file where the
253           process ID (pid) of the TPM will be written into. It is also
254           possible to pass a file descriptor to a file that has been opened
255           for writing.
256
257       -r|--runas <owner>
258           Switch to the given user. This option can only be used when swtpm
259           is started as root.
260
261       -R|--chroot <path<gt>
262           Chroot to the given directory at startup. This option can only be
263           used when swtpm is started as root.
264
265       --seccomp action=none|log|kill (since v0.2)
266           This option allows a user to select the action to take by the
267           seccomp profile when a syscall is executed that is not allowed. The
268           default is kill. To disable the seccomp profile, choose none. The
269           log action logs offending syscalls.  The log action is only
270           available if libseccomp supports logging.
271
272           This option is only available on Linux and only if swtpm was
273           compiled with libseccomp support.
274
275       --flags
276       [not-need-init][,startup-clear|startup-state|startup-deactivated|startup-none][,disable-auto-shutdown]
277           The not-need-init flag enables the TPM to accept TPM commands right
278           after start without requiring an INIT to be sent to it through the
279           command channel (see the '-i' option of swtpm_ioctl).
280
281           The startup options cause a TPM_Startup or TPM2_Startup command to
282           automatically be sent. The startup-deactivated option is only valid
283           for a TPM 1.2. These options imply not-need-init, except for the
284           startup-none option, which results in no command being sent.
285
286           If --vtpm-proxy is used, startup-clear is automatically chosen but
287           this can be changed with this option.
288
289           The disable-auto-shutdown flag prevents swtpm from automatically
290           sending a TPM2_Shutdown() before the reset of a TPM 2 or before the
291           swtpm process is terminated. When this flag is not provide swtpm
292           will send this command to avoid increasing the dictionary attack
293           (DA) lockout counter and ulimately a DA lockout by the TPM 2 due to
294           omission of sending a required TPM2_Shutdown() before TPM 2 reset
295           or swtpm process termination.
296
297       --print-capabilities (since v0.2)
298           Print capabilities that were added to swtpm after version 0.1. The
299           output may contain the following:
300
301               {
302                 "type": "swtpm",
303                 "features": [
304                   "tpm-1.2",
305                   "tpm-2.0",
306                   "cmdarg-seccomp",
307                   "cmdarg-key-fd",
308                   "cmdarg-pwd-fd",
309                   "cmdarg-print-states",
310                   "cmdarg-chroot",
311                   "cmdarg-migration",
312                   "nvram-backend-dir",
313                   "nvram-backend-file",
314                   "tpm-send-command-header",
315                   "flags-opt-startup",
316                   "flags-opt-disable-auto-shutdown",
317                   "rsa-keysize-1024",
318                   "rsa-keysize-2048",
319                   "rsa-keysize-3072"
320                 ],
321                 "version": "0.7.0"
322               }
323
324           The version field is available since v0.7.
325
326           The meaning of the feature verbs is as follows:
327
328           tpm-1.2 (since v0.7)
329               TPM 1.2 emulation is supported (libtpms is compiled with 1.2
330               support).
331
332           tpm-2.0 (since v0.7)
333               TPM 2 emulation is supported (libtpms is compiled with 2.0
334               support).
335
336               (the --tpm2 option is supported)
337
338           cmdarg-seccomp (since v0.2)
339               The --seccomp option is supported.
340
341           cmdarg-key-fd (since v0.2)
342               The --key option supports the fd= parameter.
343
344           cmdarg-pwd-fd (since v0.2)
345               The --key option supports the pwdfd= parameter.
346
347           cmdarg-print-states (since v0.7)
348               The --print-states option is supported.
349
350           cmdarg-chroot (since v0.8)
351               The --chroot option is supported.
352
353           cmdarg-migration (since v0.8)
354               The --migration option is supported.
355
356           nvram-backend-dir (since v0.7)
357               The --tpmstate option supports the backend-uri=dir://...
358               parameter.
359
360           nvram-backend-file (since v0.7)
361               The --tpmstate option supports the backend-uri=file://...
362               parameter.
363
364           tpm-send-command-header (since v0.2)
365               The TPM 2 commands may be prefixed by a header that carries a
366               4-byte command, 1 byte for locality, and 4-byte TPM 2 command
367               length indicator.  The TPM 2 will respond by preprending a
368               4-byte response indicator and a 4-byte trailer. All data is
369               sent in big endian format.
370
371           flags-opt-startup (since v0.3)
372               The --flags option supports the startup-... options.
373
374           flags-opt-disable-auto-shutdown (since v0.8)
375               The --flags option supports the disable-auto-shutdown flag.
376
377           rsa-keysize-2048 (since v0.4)
378               The TPM 2 supports the shown RSA key sizes. If none of the rsa-
379               keysize verbs is shown then only RSA 2048 bit keys are
380               supported.
381
382       --print-states (since v0.7)
383           This option allows to print out the TPM 1.2 or TPM 2 state blobs
384           that are currently stored in a storage backend. This option
385           requires that the storage backend be specified using the --tpmstate
386           option and if TPM 2 state blobs are supposed to be shown, the
387           --tpm2 option must be passed.
388
389           The following shows the JSON output of this option. It indicates
390           that the 'permall' and 'volatile' states are available.
391
392               {
393                 "type": "swtpm",
394                 "states": [
395                   {
396                     "name": "permall",
397                     "size": 6013
398                   }, {
399                     "name": "volatile",
400                     "size": 1087
401                   }
402                 ]
403               }
404
405       --migration [incoming][,release-lock-outgoing]
406           This option allows to control the locking of the NVRAM storage for
407           the purpose of supporting migration between hosts that have shared
408           storage setup for the swtpm's state directory and if locking is
409           supported by the storage backend. The directory storage backend for
410           example supports locking and therefore requires usage of this
411           option in case of shared storage.  When providing the incoming
412           option parameter swtpm defers the locking of the NVRAM until the
413           state blobs are received or until the first TPM command is
414           processed if no state blobs were received.  The release-lock-
415           outgoing option parameter causes swtpm to release any NVRAM lock
416           once the TPM's 'savestate' blob is received from swtpm. To avoid
417           releasing the lock too early the 'permanent' and 'volatile' state
418           blobs must be received before the 'savestate' blob.
419
420       -h|--help
421           Display usage info.
422

NOTES

424       If a TPM 2 is used, the user is typically required to send a
425       TPM2_Shutdown() command to a TPM 2 to avoid possibly increasing the
426       TPM_PT_LOCKOUT_COUNTER that may lead to a dictionary attack (DA)
427       lockout upon next startup (TPM2_Startup()) of the TPM 2. Whether the
428       TPM_PT_LOCKOUT_COUNTER is increased depends on previous commands sent
429       to the TPM 2 as well as internal state of the TPM 2. One example that
430       will trigger the counter to increase is the omission of a password when
431       trying to access a password-protected object or NVRAM location that has
432       the DA attribute set, followed by termination of swtpm without sending
433       TPM2_Shutdown(). To avoid a DA lockout swtpm will make a best-effort
434       and send a TPM2_Shutdown(SU_STATE) or TPM2_Shutdown(SU_CLEAR) if found
435       necessary.
436

SEE ALSO

438       swtpm_bios, swtpm_cuse
439
440
441
442swtpm                             2023-08-16                          swtpm(8)
Impressum