man/man8/swtpm_cuse.pod - third_party/github.com/stefanberger/swtpm - Git at Google

 =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<--flags [not-need-init] [,startup-clear|startup-state|startup-deactivated|startup-none]>

 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.

 =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"
       ],
       "version": "0.7.0"
     }

 The version field is available since 0.7.

 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>
	=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<--flags [not-need-init] [,startup-clear\|startup-state\|startup-deactivated\|startup-none]>

	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.

	=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"
	],
	"version": "0.7.0"
	}

	The version field is available since 0.7.

	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>