1swtpm(8) swtpm(8)
2
6 swtpm - TPM Emulator for TPM 1.2 and 2.0
7
9 swtpm socket [OPTIONS]
10 swtpm chardev [OPTIONS]
12 swtpm cuse [OPTIONS]
14
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 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 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 The swtpm process can be gracefully terminated by sending a SIGTERM
30 signal to it.
31 The swtpm cuse version requires root rights to start the TPM.
33
35 The following options are supported if the socket interface is chosen:
36 -p|--port <port>
38 Use the given port rather than using the environment variable
39 TPM_PORT.
40 -t|--terminate
42 Terminate the TPM after the client has closed the data channel
43 connection (TCP only).
44 --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 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 --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
70 The following options are supported if the chardev interface is chosen:
71 -c|--chardev <device path>
73 Use the given device to listen for TPM commands and send response
74 on.
75 --vtpm-proxy
77 Create a Linux vTPM proxy device instance and read TPM commands
78 from its backend device.
79
81 The following options are supported if the cuse interface is chosen:
82 -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 -M|--maj <MAJOR>
88 Create the device with the given major number.
89 -m|--min <MINOR>
91 Create the device with the given minor number.
92
94 The following options are supported by the socket and character device
95 interfaces:
96 -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 -d|--daemon
103 Daemonize the process.
104 --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 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 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 The control channel enables out-of-band control of the TPM, such as
131 resetting the TPM.
132
134 The following options are support by all interfaces:
135 --tpmstate dir=<dir>[,mode=<0...>]|backend-uri=<uri>
137 Use the given path rather than using the environment variable
138 TPM_PATH.
139 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 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 --tpm2
156 Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
157 --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 The level parameter allows a user to choose the level of logging.
163 Starting at log level 5, libtpms debug logging is activated.
164 All logged lines will be prefixed with prefix. By default no prefix
166 is prepended.
167 If truncate is passed, the log file will be truncated.
169 --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 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 --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 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 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 The remove parameter will attempt to remove the given keyfile once
199 the key has been read.
200 --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 --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 The migration key and the key used for encrypting the TPM state
217 files may be the same.
218 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 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 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 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 The remove parameter will attempt to remove the given keyfile once
243 the key has been read.
244 --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 --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 -r|--runas <owner>
258 Switch to the given user. This option can only be used when swtpm
259 is started as root.
260 -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 --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 This option is only available on Linux and only if swtpm was
273 compiled with libseccomp support.
274 --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 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 If --vtpm-proxy is used, startup-clear is automatically chosen but
287 this can be changed with this option.
288 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 --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 {
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 The version field is available since v0.7.
325 The meaning of the feature verbs is as follows:
327 tpm-1.2 (since v0.7)
329 TPM 1.2 emulation is supported (libtpms is compiled with 1.2
330 support).
331 tpm-2.0 (since v0.7)
333 TPM 2 emulation is supported (libtpms is compiled with 2.0
334 support).
335 (the --tpm2 option is supported)
337 cmdarg-seccomp (since v0.2)
339 The --seccomp option is supported.
340 cmdarg-key-fd (since v0.2)
342 The --key option supports the fd= parameter.
343 cmdarg-pwd-fd (since v0.2)
345 The --key option supports the pwdfd= parameter.
346 cmdarg-print-states (since v0.7)
348 The --print-states option is supported.
349 cmdarg-chroot (since v0.8)
351 The --chroot option is supported.
352 cmdarg-migration (since v0.8)
354 The --migration option is supported.
355 nvram-backend-dir (since v0.7)
357 The --tpmstate option supports the backend-uri=dir://...
358 parameter.
359 nvram-backend-file (since v0.7)
361 The --tpmstate option supports the backend-uri=file://...
362 parameter.
363 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 flags-opt-startup (since v0.3)
372 The --flags option supports the startup-... options.
373 flags-opt-disable-auto-shutdown (since v0.8)
375 The --flags option supports the disable-auto-shutdown flag.
376 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 --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 The following shows the JSON output of this option. It indicates
390 that the 'permall' and 'volatile' states are available.
391 {
393 "type": "swtpm",
394 "states": [
395 {
396 "name": "permall",
397 "size": 6013
398 }, {
399 "name": "volatile",
400 "size": 1087
401 }
402 ]
403 }
404 --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 -h|--help
421 Display usage info.
422
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
438 swtpm_bios, swtpm_cuse
439swtpm 2023-08-15 swtpm(8)