[swtpm.git] / man / man8 / swtpm_cuse.pod

=head1 NAME

swtpm

=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>[,format=E<lt>hex|binaryE<gt>][,mode=aes-cbc],[remove[=true|false]]>

Enable encryption of the state files of the TPM. The keyfile must contain
an AES key of supported size; currently only 128 bit (16 bytes) keys are
supported.

The key may be in binary format, in which case the file size must be 16 bytes.
If the key is in hex format (default), the key may consist of 32 hex digits
starting with an optional '0x'.

The I<mode> parameter indicates which block chaining mode is to be used.
Currently only aes-cbc is supported.

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>[,mode=aes-cbc],[remove[=true|false]]>

This variant of the key parameter allows to provide a passphrase in a file.
A maximum of 32 bytes are read from the file and a key is derived from it using a
SHA512 hash. Currently only 128 bit keys are supported.

=item B<--migration-key file=E<lt>keyfileE<gt>[,format=E<lt>hex|binaryE<gt>][,mode=aes-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 of the TPM.
The keyfile must contain an AES key of supported size; currently only 128 bit (16 bytes)
keys are supported.

The key may be in binary format, in which case the file size must be 16 bytes.
If the key is in hex format (default), the key may consist of 32 hex digits
starting with an optional '0x'.

The I<mode> parameter indicates which block chaining mode is to be used.
Currently only aes-cbc is supported.

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>[,mode=aes-cbc],[remove[=true|false]]>

This variant of the migration key parameter allows to provide a passphrase in a file.
A maximum of 32 bytes are read from the file and a key is derived from it using a
SHA512 hash. Currently only 128 bit keys are supported.

=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.

=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>
Commit	Line	Data
f163b202 SB	1	=head1 NAME
	2
	3	swtpm
	4
	5	=head1 SYNOPSIS
	6
	7	B<swtpm_cuse [OPTIONS]>
	8
	9	=head1 DESCRIPTION
	10
	11	B<swtpm_cuse> implements a TPM software emulator built on libtpms.
bc525ccd	12	It provides access to TPM functionality over a Linux CUSE
f163b202 SB	13	(character device in user space) interface.
f163b202 SB	14
f163b202 SB	15	The B<swtpm_ioctl> command should be used for a graceful shutdown
	16	of the CUSE TPM.
	17
	18	The following options are supported:
	19
	20	=over 4
	21
	22	=item B<-h \| --help>
	23
	24	Display help screen.
	25
bc525ccd SB	26	=item B<--tpmstate dir=E<lt>dirE<gt>>
	27
	28	This parameter allows to set the directory where the TPM will
	29	store its persistent state to. If this parameter is not set,
	30	the environment variable I<TPM_PATH> can be set instead.
	31
f163b202 SB	32	=item B<-n E<lt>device nameE<gt> \| --name=E<lt>device nameE<gt> (mandatory)>
	33
	34	The name of the character device to create. To create /dev/vtpm-200, the
	35	given device name must be vtpm-200. The character device will be created
	36	automatically and use unused major and minor numbers unless they
	37	are explicitly requested through options.
	38
	39	=item B<-M E<lt>majorE<gt> \| --maj=E<lt>majorE<gt>>
	40
	41	The device major number to use; can be omitted.
	42
	43	=item B<-m E<lt>minorE<gt> \| --min=E<lt>minorE<gt>>
	44
	45	The device minor number to use; can be omitted.
	46
fbc596ab SB	47	=item B<--tpm2>
	48
	49	Choose TPM 2 functionality; by default a TPM 1.2 is chosen.
	50
f163b202 SB	51	=item B<-r E<lt>userE<gt> \| --runas=E<lt>userE<gt>>
	52
	53	The user to switch to and drop privileges.
	54
3760c342	55	=item B<--log fd=E<lt>fdE<gt>\|file=E<lt>pathE<gt>[,level=E<lt>nE<gt>]>[,prefix=E<lt>prefixE<gt>][,truncate]
f163b202 SB	56
	57	Enable logging to a file given its file descriptor or its path. Use '-' for path to
	58	suppress the logging.
	59
c7c657ec SB	60	The level parameter allows to choose the level of logging. Starting at log
	61	level 5, libtpms debug logging is activated.
	62
93f4a389 SB	63	All logged lines will be prefixed with prefix. By default no prefix is prepended.
93f4a389 SB	64
3760c342 SB	65	If I<truncate> is passed, the log file will be truncated.
3760c342 SB	66
a2f81ea2	67	=item B<--locality [reject-locality-4][,allow-set-locality]>
4a565414 SB	68
	69	The I<reject-locality-4> parameter will cause TPM error messages to be
	70	returned for requests to set the TPM into locality 4.
	71
a2f81ea2 SB	72	The I<allow-set-locality> parameter allows the swtpm to receive
	73	TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux
	74	VTPM proxy driver access is enabled by file descriptor passing.
	75	This option is implied by the I<--vtpm-proxy> option and therefore need not
	76	be explicity set if this option is passed. In all other cases care should be
	77	taken as to who can send the TPM/TPM2_SetLocality command.
	78
f163b202 SB	79	=item B<--key file=E<lt>keyfileE<gt>[,format=E<lt>hex\|binaryE<gt>][,mode=aes-cbc],[remove[=true\|false]]>
	80
	81	Enable encryption of the state files of the TPM. The keyfile must contain
	82	an AES key of supported size; currently only 128 bit (16 bytes) keys are
	83	supported.
	84
	85	The key may be in binary format, in which case the file size must be 16 bytes.
	86	If the key is in hex format (default), the key may consist of 32 hex digits
	87	starting with an optional '0x'.
	88
	89	The I<mode> parameter indicates which block chaining mode is to be used.
	90	Currently only aes-cbc is supported.
	91
	92	The I<remove> parameter will attempt to remove the given keyfile once the key
	93	has been read.
	94
	95	=item B<--key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc],[remove[=true\|false]]>
	96
	97	This variant of the key parameter allows to provide a passphrase in a file.
	98	A maximum of 32 bytes are read from the file and a key is derived from it using a
	99	SHA512 hash. Currently only 128 bit keys are supported.
	100
1680c41d SB	101	=item B<--migration-key file=E<lt>keyfileE<gt>[,format=E<lt>hex\|binaryE<gt>][,mode=aes-cbc],[remove[=true\|false]]>
	102
	103	The availability of a migration key ensures that the state of the TPM
	104	will not be revealed in unencrypted form by the swtpm_cuse program when
	105	the TPM state blobs are retreived through the ioctl interface.
	106	The migration key is not used for encrypting TPM state written to files,
	107	this is what the <I>--key<I> parameter is used for.
	108
	109	The migration key and the key used for encrypting the TPM state files may be the same.
	110
	111	While the key for the TPM state files needs to stay with those files it encrypts, the
	112	migration key needs to stay with the TPM state blobs. If for example the state of the
	113	TPM is migrated between hosts in a data center, then the TPM migration key must be
	114	available at all the destinations, so in effect it may have to be a key shared across
	115	all machines in the datacenter. In contrast to that, the key used for encrypting the
	116	TPM state <B>files<B> can be different for each TPM and need only be available
	117	on the host where the TPM state resides.
	118
	119	The migration key enables the encryption of the TPM state blobs of the TPM.
	120	The keyfile must contain an AES key of supported size; currently only 128 bit (16 bytes)
	121	keys are supported.
	122
	123	The key may be in binary format, in which case the file size must be 16 bytes.
	124	If the key is in hex format (default), the key may consist of 32 hex digits
	125	starting with an optional '0x'.
	126
	127	The I<mode> parameter indicates which block chaining mode is to be used.
	128	Currently only aes-cbc is supported.
	129
	130	The I<remove> parameter will attempt to remove the given keyfile once the key
	131	has been read.
	132
	133	=item B<--migration-key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc],[remove[=true\|false]]>
	134
	135	This variant of the migration key parameter allows to provide a passphrase in a file.
	136	A maximum of 32 bytes are read from the file and a key is derived from it using a
	137	SHA512 hash. Currently only 128 bit keys are supported.
	138
db608775	139	=item B<--pid file=E<lt>pidfileE<gt>>\|fd=E<lt>filedescriptorE<gt>>
b2151737 SB	140
b2151737 SB	141	This options allows to set the name of file where the process ID (pid) of the CUSE TPM
db608775 SB	142	will be written into. The file will be written by the root user. It is also possible to
db608775 SB	143	pass a file descriptor to a file that has been opened for writing.
b2151737	144
f163b202 SB	145	=back
f163b202 SB	146
fbc596ab SB	147	=head1 EXAMPLES
	148
	149	To start the CUSE TPM and have it create the character device /dev/foo,
	150	use the following commands:
	151
	152	=over 4
	153
	154	# ensure that previous swtpm_cuse using /dev/foo is gone
	155
	156	swtpm_ioctl -s /dev/foo
	157
	158	# Start the swtpm with TPM 2 functionality and make it accessible
	159	# through /dev/foo. Have the swtpm_cuse write the TPM's persistent
	160	# state into the given directory.
	161
	162	export TPM_PATH=/tmp/foo
	163	mkdir -p $TPM_PATH
	164
	165	swtpm_cuse -n foo --tpm2
	166
	167	# Send TPM_Init to the TPM; this is absolutely necessary
	168
	169	swtpm_ioctl -i /dev/foo
	170
	171	=back
f163b202 SB	172
	173	=head1 SEE ALSO
	174
	175	B<swtpm_bios>, B<swtpm_ioctl>