+++ /dev/null
-=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>
projects / swtpm.git / blobdiff