| =head1 NAME |
| |
| swtpm_ioctl - Utility for sending control commands to swtpm |
| |
| =head1 SYNOPSIS |
| |
| B<swtpm_ioctl [COMMAND] [E<lt>deviceE<gt>>] |
| |
| =head1 DESCRIPTION |
| |
| B<swtpm_ioctl> implements a client tool for controlling the |
| I<swtpm_cuse> and I<swtpm> TPM software emulators, such as for example their |
| initialization and shutdown. Once it has been initialized, TPM commands can |
| be sent to it. |
| |
| Note: The environment variable SWTPM_IOCTL_BUFFERSIZE can be set to the size |
| for the buffer for state blob transfer to use. If it is not set, the ioctl() |
| interface is used for transferring the state. This environment variable |
| is primarily used for testing purposes. |
| |
| The following commands are supported: |
| |
| =over 4 |
| |
| =item B<--tpm-device E<lt>deviceE<gt>> |
| |
| Use the given device. The full path to the character device must be provided, such |
| as for example /dev/vtpm-200. |
| |
| This option can be used instead of providing the device as the last parameter. |
| |
| =item B<--tcp E<lt>serverE<gt>:E<lt>portE<gt>> |
| |
| Connect to the given server and port; if no server is given, 127.0.0.1 is used; |
| if port is not given, the default port 6545 is used. |
| |
| =item B<--unix E<lt>pathE<gt>> |
| |
| Connect to the given UnixIO path. |
| |
| =item B<-c> |
| |
| Get the capability flags indicating which commands are supported. |
| |
| =item B<-i> |
| |
| Send a hardware initialization signal to the swtpm_cuse/swtpm. Volatile |
| state previously written by the TPM will be read and the file automatically |
| delete. |
| |
| =item B<-s> |
| |
| Initiate a graceful shut down. |
| |
| =item B<--stop> |
| |
| Stop the swtpm_cuse/swtpm. This does not shut it down. The I<-i> command can again |
| be sent to it. After a stop it is also possible to load TPM stateblobs into the |
| TPM using the I<--load> command. |
| |
| =item B<-e> |
| |
| Get the tpmEstablished bit. |
| |
| =item B<-r locality> |
| |
| Reset the tpmEstablished bit using the given locality. Only localities 3 and 4 work. |
| This operation will not permanently change the localty that was previously set |
| using the I<-l> option. |
| |
| =item B<-l locality> |
| |
| Set the locality for the subsequent TPM commands. |
| |
| =item B<-v> |
| |
| Have the TPM write the volatile state to a file. Upon a TPM_Init (-i) the |
| TPM state will be read and the TPM can then resume operation without further |
| intialization. |
| |
| =item B<-C> |
| |
| Cancel an ongoing TPM command. |
| |
| =item B<-h data> |
| |
| Reset and extend PCR 17 with the hash of the given data. If data is the single |
| character '-', then all data are read from stdin. |
| |
| =item B<--save E<lt>TPM state blob nameE<gt> E<lt>filenameE<gt> > |
| |
| Save the TPM state blob into the given file. Valid TPM state blob |
| names are 'permanent', 'volatile', and 'savestate'. |
| |
| Note that this command can be executed at any time. However, to retrieve |
| the latest volatile state, the I<-v> command should have been run |
| immediately before running this command. The savestate blob will only be |
| returned if a TPM_SaveState command was executed in the TPM (TPM 1.2). |
| |
| =item B<--load E<lt>TPM state blob nameE<gt> E<lt>filenameE<gt>> |
| |
| Load the given TPM state blob from the given file. Valid TPM state blob |
| names are 'permanent', 'volatile', and 'savestate'. |
| |
| Note that this command can only be executed on a TPM that is shut down. |
| To then start the TPM with the uploaded state, the I<-i> command must |
| be issued. |
| |
| =item B<-g> |
| |
| Get configuration flags that for example indicate which keys (file encryption |
| or migration key) are in use by the TPM. |
| |
| =item B<--info E<lt>flagE<gt>> |
| |
| Get information about the TPM implementation in JSON format. The flag |
| I<TPMLIB_INFO_TPMSPECIFICATION>, which has the value 1, returns information |
| about the specification the TPM implementation followed. The flag |
| I<TPMLIB_INFO_TPMATTRIBUTES>, which has the value 2, returns information |
| about the manufacturer, model, and version of the TPM. |
| |
| =item B<--lock-storage E<lt>retriesE<gt>> |
| |
| Lock the storage and retry a given number of times with 10ms delay in between. |
| Locking the storage may be necessary to do after the state of the TPM has been |
| migrated out and the lock on the storage has been released when the 'savestate' |
| blob was received and now the storage should be locked again. |
| |
| =back |
| |
| =head1 EXAMPLE |
| |
| Start swtpm on port 10000 for the control port and emulate a TPM 1.2: |
| |
| #> swtpm socket --tpmstate dir=/tmp/myvtpm1 --log level=4 --ctrl type=tcp,port=10000 --server type=tcp,port=10001 --flags not-need-init |
| |
| Get information about the TPM implementation in JSON: |
| |
| #> swtpm_ioctl --tcp :10000 --info 1 |
| {"TPMSpecification":{"family":"1.2","level":2,"revision":116}} |
| #> swtpm_ioctl --tcp :10000 --info 2 |
| {"TPMAttributes":{"manufacturer":"id:00001014","version":"id:00740001","model":"swtpm"}} |
| |
| Shut down the swtpm |
| |
| #> swtpm_ioctl --tcp :10000 -s |
| |
| =head1 SEE ALSO |
| |
| B<swtpm_cuse> |
