man/man8/swtpm.pod

   1 =head1 NAME
   2
   3 swtpm - TPM Emulator for TPM 1.2 and 2.0
   4
   5 =head1 SYNOPSIS
   6
   7 B<swtpm socket [OPTIONS]>
   8
   9 B<swtpm chardev [OPTIONS]>
  10
  11 B<swtpm cuse [OPTIONS]>
  12
  13 =head1 DESCRIPTION
  14
  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.
  19
  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
  23 request messages.
  24
  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
  27 state into.
  28
  29 The B<swtpm> process can be gracefully terminated by sending a
  30 I<SIGTERM> signal to it.
  31
  32 The B<swtpm> cuse version requires root rights to start the TPM.
  33
  34 =head1 Options for socket interface
  35
  36 The following options are supported if the I<socket> interface is chosen:
  37
  38 =over 4
  39
  40 =item B<-p|--port <port>>
  41
  42 Use the given port rather than using the environment variable TPM_PORT.
  43
  44 =item B<-t|--terminate>
  45
  46 Terminate the TPM after the client has closed the connection.
  47
  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]>
  49
  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
  52 descriptor then.
  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>.
  57
  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.
  60
  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>]>
  62
  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.
  68
  69 =back
  70
  71
  72 =head1 Options for character device interface
  73
  74 The following options are supported if the I<chardev> interface is chosen:
  75
  76 =over 4
  77
  78 =item B<-c|--chardev <device path>>
  79
  80 Use the given device to listen for TPM commands and send response on.
  81
  82 =item B<--vtpm-proxy>
  83
  84 Create a Linux vTPM proxy device instance and read TPM commands from its
  85 backend device.
  86
  87 =back
  88
  89
  90 =head1 Options for the CUSE interface
  91
  92 The following options are supported if the I<cuse> interface is chosen:
  93
  94 =over 4
  95
  96 =item B<-n|--name <NAME>>
  97
  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.
 100
 101 =item B<-M|--maj <MAJOR>>
 102
 103 Create the device with the given major number.
 104
 105 =item B<-m|--min <MINOR>>
 106
 107 Create the device with the given minor number.
 108
 109 =back
 110
 111
 112 =head1 Options for socket and character device interfaces:
 113
 114 The following options are supported by the socket and character device interfaces:
 115
 116 =over 4
 117
 118 =item B<-f|--fd <fd>>
 119
 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.
 123
 124 =item B<-d|--daemon>
 125
 126 Daemonize the process.
 127
 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>] >
 129
 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>.
 136
 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.
 141
 142 The control channel enables out-of-band control of the TPM, such as resetting the TPM.
 143
 144 =back
 145
 146
 147 =head1 Options for all interfaces
 148
 149 The following options are support by all interfaces:
 150
 151 =over 4
 152
 153 =item B<--tpmstate dir=E<lt>dirE<gt>[,mode=E<lt>0...E<gt>]|backend-uri=E<lt>uriE<gt>>
 154
 155 Use the given path rather than using the environment variable TPM_PATH.
 156
 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.
 160
 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
 168 state. (since v0.7)
 169
 170 =item B<--tpm2>
 171
 172 Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
 173
 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]>
 175
 176 Enable logging to a file given its file descriptor or its path. Use '-' for path to
 177 suppress the logging.
 178
 179 The level parameter allows a user to choose the level of logging. Starting at log
 180 level 5, libtpms debug logging is activated.
 181
 182 All logged lines will be prefixed with prefix. By default no prefix is prepended.
 183
 184 If I<truncate> is passed, the log file will be truncated.
 185
 186 =item B<--locality reject-locality-4[,allow-set-locality]>
 187
 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.
 190
 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.
 197
 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]]>
 199
 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
 202 supported.
 203
 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'.
 207
 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.
 211
 212 The I<remove> parameter will attempt to remove the given keyfile once the key
 213 has been read.
 214
 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]>
 216
 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.
 220
 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]]>
 222
 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.
 228
 229 The migration key and the key used for encrypting the TPM state files may be the same.
 230
 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.
 238
 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.
 242
 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'.
 246
 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.
 250
 251 The I<remove> parameter will attempt to remove the given keyfile once the key
 252 has been read.
 253
 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]>
 255
 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.
 259
 260 =item B<--pid file=E<lt>pidfileE<gt>|fd=E<lt>filedescriptorE<gt>>
 261
 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.
 265
 266 =item B<-r|--runas E<lt>ownerE<gt>>
 267
 268 Switch to the given user. This option can only be used when swtpm is started as root.
 269
 270 =item B<--seccomp action=none|log|kill> (since v0.2)
 271
 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.
 276
 277 This option is only available on Linux and only if swtpm was compiled with
 278 libseccomp support.
 279
 280 =item B<--flags [not-need-init][,startup-clear|startup-state|startup-deactivated|startup-none][,disable-auto-shutdown]>
 281
 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).
 285
 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.
 290
 291 If I<--vtpm-proxy> is used, I<startup-clear> is automatically chosen but
 292 this can be changed with this option.
 293
 294 The I<disable-auto-shutdown> flag prevents swtpm from automatically sending a
 295 TPM2_Shutdown() before the reset of a TPM 2 or before the swtpm process
 296 is terminated. When this flag is not provide swtpm will send this command to
 297 avoid increasing the dictionary attack (DA) lockout counter and ulimately
 298 a DA lockout by the TPM 2 due to omission of sending a required TPM2_Shutdown()
 299 before TPM 2 reset or swtpm process termination.
 300
 301 =item B<--print-capabilities> (since v0.2)
 302
 303 Print capabilities that were added to swtpm after version 0.1. The output
 304 may contain the following:
 305
 306     {
 307       "type": "swtpm",
 308       "features": [
 309         "tpm-1.2",
 310         "tpm-2.0",
 311         "cmdarg-seccomp",
 312         "cmdarg-key-fd",
 313         "cmdarg-pwd-fd",
 314         "cmdarg-print-states",
 315         "nvram-backend-dir",
 316         "nvram-backend-file",
 317         "tpm-send-command-header",
 318         "flags-opt-startup",
 319         "flags-opt-disable-auto-shutdown",
 320         "rsa-keysize-1024",
 321         "rsa-keysize-2048",
 322         "rsa-keysize-3072"
 323       ],
 324       "version": "0.7.0"
 325     }
 326
 327 The version field is available since v0.7.
 328
 329 The meaning of the feature verbs is as follows:
 330
 331 =over 4
 332
 333 =item B<tpm-1.2> (since v0.7)
 334
 335 TPM 1.2 emulation is supported (libtpms is compiled with 1.2 support).
 336
 337 =item B<tpm-2.0> (since v0.7)
 338
 339 TPM 2 emulation is supported (libtpms is compiled with 2.0 support).
 340
 341 (the I<--tpm2> option is supported)
 342
 343 =item B<cmdarg-seccomp> (since v0.2)
 344
 345 The I<--seccomp> option is supported.
 346
 347 =item B<cmdarg-key-fd> (since v0.2)
 348
 349 The I<--key> option supports the I<fd=> parameter.
 350
 351 =item B<cmdarg-pwd-fd> (since v0.2)
 352
 353 The I<--key> option supports the I<pwdfd=> parameter.
 354
 355 =item B<cmdarg-print-states> (since v0.7)
 356
 357 The I<--print-states> option is supported.
 358
 359 =item B<nvram-backend-dir> (since v0.7)
 360
 361 The I<--tpmstate> option supports the I<backend-uri=dir://...>
 362 parameter.
 363
 364 =item B<nvram-backend-file> (since v0.7)
 365
 366 The I<--tpmstate> option supports the I<backend-uri=file://...>
 367 parameter.
 368
 369 =item B<tpm-send-command-header> (since v0.2)
 370
 371 The TPM 2 commands may be prefixed by a header that carries a 4-byte
 372 command, 1 byte for locality, and 4-byte TPM 2 command length indicator.
 373 The TPM 2 will respond by preprending a 4-byte response indicator and a
 374 4-byte trailer. All data is sent in big endian format.
 375
 376 =item B<flags-opt-startup> (since v0.3)
 377
 378 The I<--flags> option supports the I<startup-...> options.
 379
 380 =item B<flags-opt-disable-auto-shutdown> (since v0.8)
 381
 382 The I<--flags> option supports the I<disable-auto-shutdown> flag.
 383
 384 =item B<rsa-keysize-2048> (since v0.4)
 385
 386 The TPM 2 supports the shown RSA key sizes. If none of the
 387 rsa-keysize verbs is shown then only RSA 2048 bit keys are supported.
 388
 389 =back
 390
 391 =item B<--print-states> (since v0.7)
 392
 393 This option allows to print out the TPM 1.2 or TPM 2 state blobs
 394 that are currently stored in a storage backend. This option requires
 395 that the storage backend be specified using the I<--tpmstate> option
 396 and if TPM 2 state blobs are supposed to be shown, the I<--tpm2>
 397 option must be passed.
 398
 399 The following shows the JSON output of this option. It indicates that
 400 the 'permall' and 'volatile' states are available.
 401
 402     {
 403       "type": "swtpm",
 404       "states": [
 405         {
 406           "name": "permall",
 407           "size": 6013
 408         }, {
 409           "name": "volatile",
 410           "size": 1087
 411         }
 412       ]
 413     }
 414
 415 =item B<-h|--help>
 416
 417 Display usage info.
 418
 419 =back
 420
 421 =head1 NOTES
 422
 423 If a TPM 2 is used, the user is typically required to send a TPM2_Shutdown()
 424 command to a TPM 2 to avoid possibly increasing the TPM_PT_LOCKOUT_COUNTER
 425 that may lead to a dictionary attack (DA) lockout upon next startup
 426 (TPM2_Startup()) of the TPM 2. Whether the TPM_PT_LOCKOUT_COUNTER is
 427 increased depends on previous commands sent to the TPM 2 as well as
 428 internal state of the TPM 2. One example that will trigger the counter to
 429 increase is the omission of a password when trying to access a
 430 password-protected object or NVRAM location that has the DA attribute set,
 431 followed by termination of swtpm without sending TPM2_Shutdown(). To avoid
 432 a DA lockout swtpm will make a best-effort and send a TPM2_Shutdown(SU_STATE)
 433 or TPM2_Shutdown(SU_CLEAR) if found necessary.
 434
 435 =head1 SEE ALSO
 436
 437 B<swtpm_bios>, B<swtpm_cuse>