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 connection.
43 --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 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 --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
69 The following options are supported if the chardev interface is chosen:
70 -c|--chardev <device path>
72 Use the given device to listen for TPM commands and send response
73 on.
74 --vtpm-proxy
76 Create a Linux vTPM proxy device instance and read TPM commands
77 from its backend device.
78
80 The following options are supported if the cuse interface is chosen:
81 -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 -M|--maj <MAJOR>
87 Create the device with the given major number.
88 -m|--min <MINOR>
90 Create the device with the given minor number.
91
93 The following options are supported by the socket and character device
94 interfaces:
95 -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 -d|--daemon
102 Daemonize the process.
103 --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 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 The control channel enables out-of-band control of the TPM, such as
123 resetting the TPM.
124
126 The following options are support by all interfaces:
127 --tpmstate dir=<dir>[,mode=<0...>]|backend-uri=<uri>
129 Use the given path rather than using the environment variable
130 TPM_PATH.
131 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 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 --tpm2
148 Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
149 --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 The level parameter allows a user to choose the level of logging.
155 Starting at log level 5, libtpms debug logging is activated.
156 All logged lines will be prefixed with prefix. By default no prefix
158 is prepended.
159 If truncate is passed, the log file will be truncated.
161 --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 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 --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 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 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 The remove parameter will attempt to remove the given keyfile once
191 the key has been read.
192 --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 --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 The migration key and the key used for encrypting the TPM state
209 files may be the same.
210 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 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 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 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 The remove parameter will attempt to remove the given keyfile once
235 the key has been read.
236 --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 --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 -r|--runas <owner>
250 Switch to the given user. This option can only be used when swtpm
251 is started as root.
252 --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 This option is only available on Linux and only if swtpm was
261 compiled with libseccomp support.
262 --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 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 If --vtpm-proxy is used, startup-clear is automatically chosen but
275 this can be changed with this option.
276 --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 {
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 The version field is available since v0.7.
302 The meaning of the feature verbs is as follows:
304 tpm-1.2 (since v0.7)
306 TPM 1.2 emulation is supported (libtpms is compiled with 1.2
307 support).
308 tpm-2.0 (since v0.7)
310 TPM 2 emulation is supported (libtpms is compiled with 2.0
311 support).
312 (the --tpm2 option is supported)
314 cmdarg-seccomp (since v0.2)
316 The --seccomp option is supported.
317 cmdarg-key-fd (since v0.2)
319 The --key option supports the fd= parameter.
320 cmdarg-pwd-fd (since v0.2)
322 The --key option supports the pwdfd= parameter.
323 cmdarg-print-states (since v0.7)
325 The --print-states option is supported.
326 nvram-backend-dir (since v0.7)
328 The --tpmstate option supports the backend-uri=dir://...
329 parameter.
330 nvram-backend-file (since v0.7)
332 The --tpmstate option supports the backend-uri=file://...
333 parameter.
334 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 flags-opt-startup (since v0.3)
343 The --flags option supports the startup-... options.
344 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 --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 The following shows the JSON output of this option. It indicates
358 that the 'permall' and 'volatile' states are available.
359 {
361 "type": "swtpm",
362 "states": [
363 {
364 "name": "permall",
365 "size": 6013
366 }, {
367 "name": "volatile",
368 "size": 1087
369 }
370 ]
371 }
372 -h|--help
374 Display usage info.
375
377 swtpm_bios, swtpm_cuse
378swtpm 2021-11-09 swtpm(8)