| =head1 NAME |
| |
| swtpm - TPM Emulator for TPM 1.2 and 2.0 with a CUSE interface only |
| |
| =head1 SYNOPSIS |
| |
| B<swtpm_cuse [OPTIONS]> |
| |
| =head1 DESCRIPTION |
| |
| B<swtpm_cuse> implements a TPM software emulator built on libtpms. |
| It provides access to TPM functionality over a Linux CUSE |
| (character device in user space) interface. |
| |
| The B<swtpm_ioctl> command should be used for a graceful shutdown |
| of the CUSE TPM. |
| |
| The following options are supported: |
| |
| =over 4 |
| |
| =item B<-h | --help> |
| |
| Display help screen. |
| |
| =item B<--tpmstate dir=E<lt>dirE<gt>> |
| |
| This parameter allows to set the directory where the TPM will |
| store its persistent state to. If this parameter is not set, |
| the environment variable I<TPM_PATH> can be set instead. |
| |
| =item B<-n E<lt>device nameE<gt> | --name=E<lt>device nameE<gt> (mandatory)> |
| |
| The name of the character device to create. To create /dev/vtpm-200, the |
| given device name must be vtpm-200. The character device will be created |
| automatically and use unused major and minor numbers unless they |
| are explicitly requested through options. |
| |
| =item B<-M E<lt>majorE<gt> | --maj=E<lt>majorE<gt>> |
| |
| The device major number to use; can be omitted. |
| |
| =item B<-m E<lt>minorE<gt> | --min=E<lt>minorE<gt>> |
| |
| The device minor number to use; can be omitted. |
| |
| =item B<--tpm2> |
| |
| Choose TPM 2 functionality; by default a TPM 1.2 is chosen. |
| |
| =item B<-r E<lt>userE<gt> | --runas=E<lt>userE<gt>> |
| |
| The user to switch to and drop privileges. |
| |
| =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 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 explicity 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 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 by the swtpm_cuse program when |
| the TPM state blobs are retreived through the ioctl interface. |
| The migration key is not used for encrypting TPM state written to files, |
| this is what the <I>--key<I> 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<B> 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]][,kdf=sha512|pbkdf2]> |
| |
| This variant of the key parameter allows 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 to set the name of file where the process ID (pid) of the CUSE TPM |
| will be written into. The file will be written by the root user. It is also possible to |
| pass a file descriptor to a file that has been opened for writing. |
| |
| =item B<--seccomp action=none|log|kill> (since v0.2) |
| |
| This option allows 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<--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": [ |
| "cmdarg-seccomp", |
| "cmdarg-key-fd" |
| ] |
| } |
| |
| The meaning of the feature verbs is as follows: |
| |
| =over 4 |
| |
| =item B<cmdarg-seccomp> |
| |
| The I<--seccomp> option is supported. |
| |
| =item B<cmdarg-key-fd> |
| |
| The I<--key> option supports the I<fd=> parameter. |
| |
| =back |
| |
| =back |
| |
| =head1 EXAMPLES |
| |
| To start the CUSE TPM and have it create the character device /dev/foo, |
| use the following commands: |
| |
| =over 4 |
| |
| # ensure that previous swtpm_cuse using /dev/foo is gone |
| |
| swtpm_ioctl -s /dev/foo |
| |
| # Start the swtpm with TPM 2 functionality and make it accessible |
| # through /dev/foo. Have the swtpm_cuse write the TPM's persistent |
| # state into the given directory. |
| |
| export TPM_PATH=/tmp/foo |
| mkdir -p $TPM_PATH |
| |
| swtpm_cuse -n foo --tpm2 |
| |
| # Send TPM_Init to the TPM; this is absolutely necessary |
| |
| swtpm_ioctl -i /dev/foo |
| |
| =back |
| |
| =head1 SEE ALSO |
| |
| B<swtpm_bios>, B<swtpm_ioctl> |