| =head1 NAME |
| |
| swtpm - TPM Emulator for TPM 1.2 and 2.0 |
| |
| =head1 SYNOPSIS |
| |
| B<swtpm socket [OPTIONS]> |
| |
| B<swtpm chardev [OPTIONS]> |
| |
| B<swtpm cuse [OPTIONS]> |
| |
| =head1 DESCRIPTION |
| |
| B<swtpm> implements a TPM software emulator built on libtpms. |
| It provides access to TPM functionality over a TCP/IP socket interface |
| or it can listend for commands on a character device, or create a CUSE |
| (character device in userspace) interface for receiving of TPM commands. |
| |
| Unless corresponding command line parameters are used, the |
| B<swtpm> socket version requires that the environment variable I<TPM_PORT> |
| be set to the TCP/IP port the process is supposed to listen on for TPM |
| request messages. |
| |
| Similarly, the environment variable I<TPM_PATH> can be set and |
| contain the name of a directory where the TPM can store its persistent |
| state into. |
| |
| The B<swtpm> process can be gracefully terminated by sending a |
| I<SIGTERM> signal to it. |
| |
| The B<swtpm> cuse version requires root rights to start the TPM. |
| |
| =head1 Options for socket interface |
| |
| The following options are supported if the I<socket> interface is chosen: |
| |
| =over 4 |
| |
| =item B<-p|--port <port>> |
| |
| Use the given port rather than using the environment variable TPM_PORT. |
| |
| =item B<-t|--terminate> |
| |
| Terminate the TPM after the client has closed the connection. |
| |
| =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]> |
| |
| Expect TCP connections on the given port; if a port is not provided a file descriptor |
| must be passed with the fd parameter and the commands are read from this file |
| descriptor then. |
| If a port is provided the I<bind address> on which to listen for TCP connections |
| can be provided as well; the default bind address is 127.0.0.1. If a link |
| local IPv6 address is provided, the name of the interface to bind to must be |
| provided with I<ifname>. |
| |
| This parameter enables a persistent connection by default unless the disconnect option |
| is given. This parameter should be used rather than the -p and --fd options. |
| |
| =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>]> |
| |
| Expect UnixIO connections on the given path. If no path is provided, a file descriptor |
| must be passed instead. The mode parameter allows a user to set the file mode bits of the |
| UnixIO path. The mode bits value must be given as an octal number starting with a '0'. |
| The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. |
| This operation requires root privileges. |
| |
| =back |
| |
| |
| =head1 Options for character device interface |
| |
| The following options are supported if the I<chardev> interface is chosen: |
| |
| =over 4 |
| |
| =item B<-c|--chardev <device path>> |
| |
| Use the given device to listen for TPM commands and send response on. |
| |
| =item B<--vtpm-proxy> |
| |
| Create a Linux vTPM proxy device instance and read TPM commands from its |
| backend device. |
| |
| =back |
| |
| |
| =head1 Options for the CUSE interface |
| |
| The following options are supported if the I<cuse> interface is chosen: |
| |
| =over 4 |
| |
| =item B<-n|--name <NAME>> |
| |
| The TPM will use a device with the given name. A device with the given name |
| will be created in /dev. This is a mandatory option. |
| |
| =item B<-M|--maj <MAJOR>> |
| |
| Create the device with the given major number. |
| |
| =item B<-m|--min <MINOR>> |
| |
| Create the device with the given minor number. |
| |
| =back |
| |
| |
| =head1 Options for socket and character device interfaces: |
| |
| The following options are supported by the socket and character device interfaces: |
| |
| =over 4 |
| |
| =item B<-f|--fd <fd>> |
| |
| Use the given socket file descriptor or character device file descriptor |
| for receiving TPM commands and sending responses. |
| For the socket interface, this option automatically assumes -t. |
| |
| =item B<-d|--daemon> |
| |
| Daemonize the process. |
| |
| =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>] > |
| |
| This option adds a control channel to the TPM. The control channel can either use a UnixIO socket with |
| a given I<path> or I<filedescriptor> or it can use a TCP socket on the given I<port> or I<filedescriptor>. |
| If a port is provided the I<bind address> on which to listen for TCP connections |
| can be provided as well; the default bind address is 127.0.0.1. If a link |
| local IPv6 address is provided, the name of the interface to bind to must be |
| provided with I<ifname>. |
| |
| The mode parameter allows a user to set the file mode bits of the UnixIO path. |
| The mode bits value must be given as an octal number starting with a '0'. |
| The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. |
| This operation requires root privileges. |
| |
| The control channel enables out-of-band control of the TPM, such as resetting the TPM. |
| |
| =back |
| |
| |
| =head1 Options for all interfaces |
| |
| The following options are support by all interfaces: |
| |
| =over 4 |
| |
| =item B<--tpmstate dir=E<lt>dirE<gt>[,mode=E<lt>0...E<gt>]|backend-uri=E<lt>uriE<gt>> |
| |
| Use the given path rather than using the environment variable TPM_PATH. |
| |
| If I<dir> is specified, the TPM state files will be written to the I<dir> with |
| the given file I<mode> bits. This value must be given as an octal number starting with a '0'. |
| The default value is 0640. |
| |
| If I<backend-uri> is specified, the TPM state data will be stored to the URI. |
| Currently I<backend-uri=dir://<path_to_dir>> and I<backend-uri=file://<path_to_dir>> |
| are available. For 'dir://', the URI should specify the path to the directory where |
| files are stored. If I<path_to_dir> starts with a '/' then the path is interpreted |
| as an absolute path, otherwise it is a path relative to the current directory. |
| For 'file://', the URI should specify a single file or block device where TPM state |
| will be stored. A blockdevice must exist already and be big enough to store all |
| state. (since v0.7) |
| |
| =item B<--tpm2> |
| |
| Choose TPM 2 functionality; by default a TPM 1.2 is chosen. |
| |
| =item B<--log [fd=E<lt>fdE<gt>|file=E<lt>pathE<gt>][,level=E<lt>nE<gt>] [,prefix=E<lt>prefixE<gt>][,truncate]> |
| |
| Enable logging to a file given its file descriptor or its path. Use '-' for path to |
| suppress the logging. |
| |
| The level parameter allows a user to choose the level of logging. Starting at log |
| level 5, libtpms debug logging is activated. |
| |
| All logged lines will be prefixed with prefix. By default no prefix is prepended. |
| |
| If I<truncate> is passed, the log file will be truncated. |
| |
| =item B<--locality reject-locality-4[,allow-set-locality]> |
| |
| The I<reject-locality-4> parameter will cause TPM error messages to be |
| returned for requests to set the TPM into locality 4. |
| |
| The I<allow-set-locality> parameter allows the swtpm to receive |
| TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux |
| VTPM proxy driver access is enabled by file descriptor passing. |
| This option is implied by the I<--vtpm-proxy> option and therefore need not |
| be explicitly set if this option is passed. In all other cases care should be |
| taken as to who can send the TPM/TPM2_SetLocality command. |
| |
| =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]]> |
| |
| Enable encryption of the state files of the TPM. The keyfile must contain |
| an AES key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are |
| supported. |
| |
| The key may be in binary format, in which case the file size must be 16 or |
| 32 bytes. If the key is in hex format (default), the key may consist of 32 |
| or 64 hex digits starting with an optional '0x'. |
| |
| The I<mode> parameter indicates which block chaining mode is to be used. |
| Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
| The encrypted data is integrity protected using encrypt-then-mac. |
| |
| The I<remove> parameter will attempt to remove the given keyfile once the key |
| has been read. |
| |
| =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]> |
| |
| This variant of the key parameter allows a user to provide a passphrase in a file. |
| The file is read and a key is derived from it using either a SHA512 hash |
| or PBKDF2. By default PBKDF2 is used. |
| |
| =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]]> |
| |
| The availability of a migration key ensures that the state of the TPM |
| will not be revealed in unencrypted form when |
| the TPM state blobs are retrieved through the ioctl interface. |
| The migration key is not used for encrypting TPM state written to files, |
| this is what the I<--key> parameter is used for. |
| |
| The migration key and the key used for encrypting the TPM state files may be the same. |
| |
| While the key for the TPM state files needs to stay with those files it encrypts, the |
| migration key needs to stay with the TPM state blobs. If for example the state of the |
| TPM is migrated between hosts in a data center, then the TPM migration key must be |
| available at all the destinations, so in effect it may have to be a key shared across |
| all machines in the datacenter. In contrast to that, the key used for encrypting the |
| TPM state B<files> can be different for each TPM and need only be available |
| on the host where the TPM state resides. |
| |
| The migration key enables the encryption of the TPM state blobs. |
| The keyfile must contain an AES key of supported size; 128 bit (16 bytes) |
| and 256 bit (32 bytes) keys are supported. |
| |
| The key may be in binary format, in which case the file size must be 16 or |
| 32 bytes. If the key is in hex format (default), the key may consist of 32 |
| or 64 hex digits starting with an optional '0x'. |
| |
| The I<mode> parameter indicates which block chaining mode is to be used. |
| Currently aes-cbc (aes-128-cbc) and aes-256-cbc are supported. |
| The encrypted data is integrity protected using encrypt-then-mac. |
| |
| The I<remove> parameter will attempt to remove the given keyfile once the key |
| has been read. |
| |
| =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]> |
| |
| This variant of the key parameter allows a user to provide a passphrase in a file. |
| The file is read and a key is derived from it using either a SHA512 hash |
| or PBKDF2. By default PBKDF2 is used. |
| |
| =item B<--pid file=E<lt>pidfileE<gt>|fd=E<lt>filedescriptorE<gt>> |
| |
| This options allows a user to set the name of file where the process ID (pid) of the TPM |
| will be written into. It is also possible to pass a file descriptor to a file that |
| has been opened for writing. |
| |
| =item B<-r|--runas E<lt>ownerE<gt>> |
| |
| Switch to the given user. This option can only be used when swtpm is started as root. |
| |
| =item B<--seccomp action=none|log|kill> (since v0.2) |
| |
| This option allows a user to select the action to take by the seccomp profile when |
| a syscall is executed that is not allowed. The default is I<kill>. To disable |
| the seccomp profile, choose I<none>. The I<log> action logs offending syscalls. |
| The I<log> action is only available if libseccomp supports logging. |
| |
| This option is only available on Linux and only if swtpm was compiled with |
| libseccomp support. |
| |
| =item B<--flags [not-need-init][,startup-clear|startup-state|startup-deactivated|startup-none][,disable-auto-shutdown]> |
| |
| The I<not-need-init> flag enables the TPM to accept TPM commands right after |
| start without requiring an INIT to be sent to it through the command channel |
| (see the '-i' option of swtpm_ioctl). |
| |
| The I<startup> options cause a TPM_Startup or TPM2_Startup command to |
| automatically be sent. The I<startup-deactivated> option is only valid for |
| a TPM 1.2. These options imply I<not-need-init>, except for the |
| I<startup-none> option, which results in no command being sent. |
| |
| If I<--vtpm-proxy> is used, I<startup-clear> is automatically chosen but |
| this can be changed with this option. |
| |
| The I<disable-auto-shutdown> flag prevents swtpm from automatically sending a |
| TPM2_Shutdown() before the reset of a TPM 2 or before the swtpm process |
| is terminated. When this flag is not provide swtpm will send this command to |
| avoid increasing the dictionary attack (DA) lockout counter and ulimately |
| a DA lockout by the TPM 2 due to omission of sending a required TPM2_Shutdown() |
| before TPM 2 reset or swtpm process termination. |
| |
| =item B<--print-capabilities> (since v0.2) |
| |
| Print capabilities that were added to swtpm after version 0.1. The output |
| may contain the following: |
| |
| { |
| "type": "swtpm", |
| "features": [ |
| "tpm-1.2", |
| "tpm-2.0", |
| "cmdarg-seccomp", |
| "cmdarg-key-fd", |
| "cmdarg-pwd-fd", |
| "cmdarg-print-states", |
| "nvram-backend-dir", |
| "nvram-backend-file", |
| "tpm-send-command-header", |
| "flags-opt-startup", |
| "flags-opt-disable-auto-shutdown", |
| "rsa-keysize-1024", |
| "rsa-keysize-2048", |
| "rsa-keysize-3072" |
| ], |
| "version": "0.7.0" |
| } |
| |
| The version field is available since v0.7. |
| |
| The meaning of the feature verbs is as follows: |
| |
| =over 4 |
| |
| =item B<tpm-1.2> (since v0.7) |
| |
| TPM 1.2 emulation is supported (libtpms is compiled with 1.2 support). |
| |
| =item B<tpm-2.0> (since v0.7) |
| |
| TPM 2 emulation is supported (libtpms is compiled with 2.0 support). |
| |
| (the I<--tpm2> option is supported) |
| |
| =item B<cmdarg-seccomp> (since v0.2) |
| |
| The I<--seccomp> option is supported. |
| |
| =item B<cmdarg-key-fd> (since v0.2) |
| |
| The I<--key> option supports the I<fd=> parameter. |
| |
| =item B<cmdarg-pwd-fd> (since v0.2) |
| |
| The I<--key> option supports the I<pwdfd=> parameter. |
| |
| =item B<cmdarg-print-states> (since v0.7) |
| |
| The I<--print-states> option is supported. |
| |
| =item B<nvram-backend-dir> (since v0.7) |
| |
| The I<--tpmstate> option supports the I<backend-uri=dir://...> |
| parameter. |
| |
| =item B<nvram-backend-file> (since v0.7) |
| |
| The I<--tpmstate> option supports the I<backend-uri=file://...> |
| parameter. |
| |
| =item B<tpm-send-command-header> (since v0.2) |
| |
| The TPM 2 commands may be prefixed by a header that carries a 4-byte |
| command, 1 byte for locality, and 4-byte TPM 2 command length indicator. |
| The TPM 2 will respond by preprending a 4-byte response indicator and a |
| 4-byte trailer. All data is sent in big endian format. |
| |
| =item B<flags-opt-startup> (since v0.3) |
| |
| The I<--flags> option supports the I<startup-...> options. |
| |
| =item B<flags-opt-disable-auto-shutdown> (since v0.8) |
| |
| The I<--flags> option supports the I<disable-auto-shutdown> flag. |
| |
| =item B<rsa-keysize-2048> (since v0.4) |
| |
| The TPM 2 supports the shown RSA key sizes. If none of the |
| rsa-keysize verbs is shown then only RSA 2048 bit keys are supported. |
| |
| =back |
| |
| =item B<--print-states> (since v0.7) |
| |
| This option allows to print out the TPM 1.2 or TPM 2 state blobs |
| that are currently stored in a storage backend. This option requires |
| that the storage backend be specified using the I<--tpmstate> option |
| and if TPM 2 state blobs are supposed to be shown, the I<--tpm2> |
| option must be passed. |
| |
| The following shows the JSON output of this option. It indicates that |
| the 'permall' and 'volatile' states are available. |
| |
| { |
| "type": "swtpm", |
| "states": [ |
| { |
| "name": "permall", |
| "size": 6013 |
| }, { |
| "name": "volatile", |
| "size": 1087 |
| } |
| ] |
| } |
| |
| =item B<-h|--help> |
| |
| Display usage info. |
| |
| =back |
| |
| =head1 NOTES |
| |
| If a TPM 2 is used, the user is typically required to send a TPM2_Shutdown() |
| command to a TPM 2 to avoid possibly increasing the TPM_PT_LOCKOUT_COUNTER |
| that may lead to a dictionary attack (DA) lockout upon next startup |
| (TPM2_Startup()) of the TPM 2. Whether the TPM_PT_LOCKOUT_COUNTER is |
| increased depends on previous commands sent to the TPM 2 as well as |
| internal state of the TPM 2. One example that will trigger the counter to |
| increase is the omission of a password when trying to access a |
| password-protected object or NVRAM location that has the DA attribute set, |
| followed by termination of swtpm without sending TPM2_Shutdown(). To avoid |
| a DA lockout swtpm will make a best-effort and send a TPM2_Shutdown(SU_STATE) |
| or TPM2_Shutdown(SU_CLEAR) if found necessary. |
| |
| =head1 SEE ALSO |
| |
| B<swtpm_bios>, B<swtpm_cuse> |