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 connection.
43
44       --server [type=tcp][,port=<port>[,bindaddr=<address>
45       [,ifname=<ifname>]]][,fd=<fd>][,disconnect]
46           Expect TCP connections on the given port; if a port is not provided
47           a file descriptor must be passed with the fd parameter and the
48           commands are read from this file descriptor then.  If a port is
49           provided the bind address on which to listen for TCP connections
50           can be provided as well; the default bind address is 127.0.0.1. If
51           a link local IPv6 address is provided, the name of the interface to
52           bind to must be provided with ifname.
53
54           This parameter enables a persistent connection by default unless
55           the disconnect option is given. This parameter should be used
56           rather than the -p and --fd options.
57
58       --server type=unixio[,path=<path>][,fd=<fd>]
59       [,mode=<0...>][,uid=<uid>][,gid=<gid>]
60           Expect UnixIO connections on the given path. If no path is
61           provided, a file descriptor must be passed instead. The mode
62           parameter allows a user to set the file mode bits of the UnixIO
63           path. The mode bits value must be given as an octal number starting
64           with a '0'.  The default value is 0770. uid and gid set the
65           ownership of the UnixIO socket's path.  This operation requires
66           root privileges.
67

Options for character device interface

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

Options for the CUSE interface

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

Options for socket and character device interfaces:

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

Options for all interfaces

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

SEE ALSO

377       swtpm_bios, swtpm_cuse
378
379
380
381swtpm                             2021-11-09                          swtpm(8)
Impressum