3 swtpm - TPM Emulator for TPM 1.2 and 2.0
7 B<swtpm socket [OPTIONS]>
9 B<swtpm chardev [OPTIONS]>
11 B<swtpm cuse [OPTIONS]>
15 B<swtpm> implements a TPM software emulator built on libtpms.
16 It provides access to TPM functionality over a TCP/IP socket interface
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.
20 Unless corresponding command line parameters are used, the
21 B<swtpm> socket version requires that the environment variable I<TPM_PORT>
22 be set to the TCP/IP port the process is supposed to listen on for TPM
25 Similarly, the environment variable I<TPM_PATH> can be set and
26 contain the name of a directory where the TPM can store its persistent
29 The B<swtpm> process can be gracefully terminated by sending a
30 I<SIGTERM> signal to it.
32 The B<swtpm> cuse version requires root rights to start the TPM.
34 =head1 Options for socket interface
36 The following options are supported if the I<socket> interface is chosen:
40 =item B<-p|--port <port>>
42 Use the given port rather than using the environment variable TPM_PORT.
44 =item B<-t|--terminate>
46 Terminate the TPM after the client has closed the connection.
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]>
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
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
55 local IPv6 address is provided, the name of the interface to bind to must be
56 provided with I<ifname>.
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.
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>]>
63 Expect UnixIO connections on the given path. If no path is provided, a file descriptor
64 must be passed instead. The mode parameter allows a user to set the file mode bits of the
65 UnixIO path. The mode bits value must be given as an octal number starting with a '0'.
66 The default value is 0770. uid and gid set the ownership of the UnixIO socket's path.
67 This operation requires root privileges.
72 =head1 Options for character device interface
74 The following options are supported if the I<chardev> interface is chosen:
78 =item B<-c|--chardev <device path>>
80 Use the given device to listen for TPM commands and send response on.
84 Create a Linux vTPM proxy device instance and read TPM commands from its
90 =head1 Options for the CUSE interface
92 The following options are supported if the I<cuse> interface is chosen:
96 =item B<-n|--name <NAME>>
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.
101 =item B<-M|--maj <MAJOR>>
103 Create the device with the given major number.
105 =item B<-m|--min <MINOR>>
107 Create the device with the given minor number.
112 =head1 Options for socket and character device interfaces:
114 The following options are supported by the socket and character device interfaces:
118 =item B<-f|--fd <fd>>
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.
126 Daemonize the process.
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>] >
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>.
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
134 local IPv6 address is provided, the name of the interface to bind to must be
135 provided with I<ifname>.
137 The mode parameter allows a user to set the file mode bits of the UnixIO path.
138 The mode bits value must be given as an octal number starting with a '0'.
139 The default value is 0770. uid and gid set the ownership of the UnixIO socket's path.
140 This operation requires root privileges.
142 The control channel enables out-of-band control of the TPM, such as resetting the TPM.
147 =head1 Options for all interfaces
149 The following options are support by all interfaces:
153 =item B<--tpmstate dir=E<lt>dirE<gt>[,mode=E<lt>0...E<gt>]|backend-uri=E<lt>uriE<gt>>
155 Use the given path rather than using the environment variable TPM_PATH.
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'.
159 The default value is 0640.
161 If I<backend-uri> is specified, the TPM state data will be stored to the URI.
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
172 Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
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]>
176 Enable logging to a file given its file descriptor or its path. Use '-' for path to
177 suppress the logging.
179 The level parameter allows a user to choose the level of logging. Starting at log
180 level 5, libtpms debug logging is activated.
182 All logged lines will be prefixed with prefix. By default no prefix is prepended.
184 If I<truncate> is passed, the log file will be truncated.
186 =item B<--locality reject-locality-4[,allow-set-locality]>
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.
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
195 be explicitly set if this option is passed. In all other cases care should be
196 taken as to who can send the TPM/TPM2_SetLocality command.
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]]>
200 Enable encryption of the state files of the TPM. The keyfile must contain
201 an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are
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'.
208 The I<mode> parameter indicates which block chaining mode is to be used.
209 Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported.
210 The encrypted data is integrity protected using encrypt-then-mac.
212 The I<remove> parameter will attempt to remove the given keyfile once the key
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]>
217 This variant of the key parameter allows a user to provide a passphrase in a file.
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.
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]]>
223 The availability of a migration key ensures that the state of the TPM
224 will not be revealed in unencrypted form when
225 the TPM state blobs are retrieved through the ioctl interface.
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.
229 The migration key and the key used for encrypting the TPM state files may be the same.
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.
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.
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'.
247 The I<mode> parameter indicates which block chaining mode is to be used.
248 Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported.
249 The encrypted data is integrity protected using encrypt-then-mac.
251 The I<remove> parameter will attempt to remove the given keyfile once the key
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]>
256 This variant of the key parameter allows a user to provide a passphrase in a file.
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.
260 =item B<--pid file=E<lt>pidfileE<gt>|fd=E<lt>filedescriptorE<gt>>
262 This options allows a user to set the name of file where the process ID (pid) of the TPM
263 will be written into. It is also possible to pass a file descriptor to a file that
264 has been opened for writing.
266 =item B<-r|--runas E<lt>ownerE<gt>>
268 Switch to the given user. This option can only be used when swtpm is started as root.
270 =item B<--seccomp action=none|log|kill> (since v0.2)
272 This option allows a user to select the action to take by the seccomp profile when
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.
277 This option is only available on Linux and only if swtpm was compiled with
280 =item B<--flags [not-need-init] [,startup-clear|startup-state|startup-deactivated|startup-none]>
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).
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.
291 If I<--vtpm-proxy> is used, I<startup-clear> is automatically chosen but
292 this can be changed with this option.
294 =item B<--print-capabilities> (since v0.2)
296 Print capabilities that were added to swtpm after version 0.1. The output
297 may contain the following:
307 "cmdarg-print-states",
309 "nvram-backend-file",
310 "tpm-send-command-header",
319 The version field is available since 0.7.
321 The meaning of the feature verbs is as follows:
327 TPM 1.2 emulation is supported (libtpms is compiled with 1.2 support).
333 TPM 2 emulation is supported (libtpms is compiled with 2.0 support).
335 (the I<--tpm2> option is supported)
339 =item B<cmdarg-seccomp>
341 The I<--seccomp> option is supported.
343 =item B<cmdarg-key-fd>
345 The I<--key> option supports the I<fd=> parameter.
347 =item B<cmdarg-pwd-fd>
349 The I<--key> option supports the I<pwdfd=> parameter.
351 =item B<cmdarg-print-states>
353 The I<--print-states> option is supported.
355 =item B<nvram-backend-dir>
357 The I<--tpmstate> option supports the I<backend-uri=dir://...>
360 =item B<nvram-backend-file>
362 The I<--tpmstate> option supports the I<backend-uri=file://...>
365 =item B<tpm-send-command-header>
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.
372 =item B<flags-opt-startup>
374 The I<--flags> option supports the I<startup-...> options.
376 =item B<rsa-keysize-2048>
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.
383 =item B<--print-states>
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.
391 The following shows the JSON output of this option. It indicates that
392 the 'permall' and 'volatile' states are available.
416 B<swtpm_bios>, B<swtpm_cuse>