swtpm_ioctls - Man Page

#include <tpm_ioctl.h>

The CUSE TPM implements an ioctl interface on the CUSE TPM's character device. The ioctl's are used for out-of-band control of various TPM operations, such as its initialization, resetting, and state migration. The control channel over TCP or UnixIO sockets uses control commands for these operations.

The following is an enumeration of the supported ioctl's and control commands, along with the names of the data structure types. All ioctl's and control commands return a TPM error code in their response. Ioctl's are prefixed with PTM and control commands are prefixed with CMD.

In case of the ioctl interface, the pointer to a command's data structure is passed as the 2nd parameter to the ioctl() function. The fields in the command's data structure are to be fill out in host endianness format.

In case of control commands, the command code must be encoded as a 4 byte integer preceding the command's data structure. Command code and data must be written in big endian format.

PTM_GET_CAPABILITY / CMD_GET_CAPABILITY, ptm_cap

This ioctl allows the caller to check which ioctl's are implemented by the CUSE TPM. The following is a list of capability flags that may be set upon return:

PTM_CAP_INIT (since v0.1)

The PTM_INIT ioctl or CMD_INIT command is supported.

PTM_CAP_SHUTDOWN (since v0.1)

The PTM_SHUTDOWN ioctl or CMD_SHUTDOWN command is supported.

PTM_CAP_GET_TPMESTABLISHED (since v0.1)

The PTM_GET_TPMESTABLISHED ioctl or CMD_GET_TPMESTABLISHED command is supported.

PTM_CAP_SET_LOCALITY (since v0.1)

The PTM_SET_LOCALITY ioctl or CMD_SET_LOCALITY is supported.

PTM_CAP_HASHING (since v0.1)

The PTM_HASH_START, PTM_HASH_DATA, and PTM_HASH_END ioctl's or CMD_HASH_START, CMD_HASH_DATA, CMD_HASH_END commands are supported.

PTM_CAP_CANCEL_TPM_CMD (since v0.1)

The PTM_CANCEL_TPM_CMD ioctl or CMD_CANCEL_TPM_CMD command is supported.

PTM_CAP_STORE_VOLATILE (since v0.1)

The PTM_STORE_VOLATILE ioctl or CMD_STORE_VOLATILE command is supported.

PTM_CAP_RESET_TPMESTABLISHED (since v0.1)

The PTM_RESET_TPMESTABLISHED ioctl or CMD_RESET_TPMESTABLISHED command is supported.

PTM_CAP_GET_STATEBLOB (since v0.1)

The PTM_GET_STATEBLOB ioctl or CMD_GET_STATEBLOB command is supported.

PTM_CAP_SET_STATEBLOB (since v0.1)

The PTM_SET_STATEBLOB ioctl or CMD_SET_STATEBLOB command is supported.

PTM_CAP_STOP (since v0.1)

The PTM_STOP ioctl or CMD_STOP command is supported.

PTM_CAP_GET_CONFIG (since v0.1)

The PTM_GET_CONFIG ioctl or CMD_GET_CONFIG command is supported.

PTM_CAP_SET_DATAFD (since v0.1)

The CMD_SET_DATAFD command is supported. This command only applies to UnixIO and there is no support for PTM_SET_DATAFD.

PTM_CAP_SET_BUFFERSIZE (since v0.1)

The PTM_SET_BUFFERSIZE ioctl or CMD_SET_BUFFERSIZE command is supported.

PTM_CAP_LOCK_STORAGE (since v0.8)

The PTM_LOCK_STORAGE ioctl or CMD_LOCK_STORAGE command is supported.

PTM_GET_CAPABILITY / CMD_GET_CAPABILITY, ptm_cap_n

The ptm_cap_n data structure can be used for non-CUSE swtpm and looks as follows:

 struct ptm_cap_n {
    union {
       struct {
           ptm_res tpm_result; /* will always be TPM_SUCCESS (0) */
           uint32_t caps;
       } resp; /* response */
    } u;
 };

PTM_INIT / CMD_INIT, ptm_init

This ioctl must be used to initialize the TPM. It must be sent to the TPM before any TPM command is sent.

The ptm_init data structure looks as follows:

 struct ptm_init {
    union {
        struct {
            uint32_t init_flags; /* see definitions below */
        } req; /* request */
        struct {
            ptm_res tpm_result;
        } resp; /* response */
    } u;
 };

The init_flags field in the request can be used to have the TPM delete the volatile state upon startup (PTM_INIT_FLAG_DELETE_VOLATILE).

A TPM result code is returned in the tpm_result field.

PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res

This ioctl allows a user to shut down the TPM.

A TPM result code is returned in ptm_res.

PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est

This ioctl is used to check whether the TPM established flag is set.

The tpm_est data structure looks as follows:

 struct ptm_est {
    union {
        struct {
            ptm_res tpm_result;
            unsigned char bit; /* TPM established bit */
        } resp; /* response */
    } u;
 };

A TPM result code is returned in the tpm_result field.

The status of the TPM establishment flag is returned in the bit field.

PTM_SET_LOCALITY / CMD_SET_LOCALITY, ptm_loc

This ioctl is used to set the current locality. All subsequent commands will be executed in this locality until the locality is changed.

The ptm_loc data structure looks as follows:

 struct ptm_loc {
    union {
        struct {
            uint8_t loc; /* locality to set */
        } req; /* request */
        struct {
            ptm_res tpm_result;
        } resp; /* response */
    } u;
 };

The locality number must be set in the request's loc field. Valid localities are in the range of 0 to 4.

A TPM result code is returned in the tpm_result field.

PTM_HASH_START / CMD_HASH_START, ptm_res

This ioctl is used to start the hash operation that is typically initiated by writing into certain registers of locality 4 of the TPM Interface (TPM TIS). Subsequent write operations for transferring data must be done with the PTM_HASH_DATA ioctl.

A TPM result code is returned in ptm_res.

PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata

This command is used to transfer the data for the hash operation.

The ptm_hdata structure looks as follows:

 struct ptm_hdata {
    union {
        struct {
            uint32_t length;
            uint8_t data[4096];
        } req; /* request */
        struct {
            ptm_res tpm_result;
        } resp; /* response */
    } u;
 };

The length of the data is indicated in the length field with the data in the data field. Up to 4096 bytes can be transferred in one call.

A TPM result code is returned in the tpm_result field.

PTM_HASH_END / CMD_HASH_END, ptm_res

This command is used to indicate the end of a hash operation that was started with the PTM_HASH_START ioctl.

A TPM result code is returned in ptm_res.

PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res

This command is used to cancel a TPM command.

A TPM result code is returned in ptm_res.

PTM_STORE_VOLATILE / CMD_STORE_VOLATILE, ptm_res

This command is used to trigger the TPM to store the volatile state into a file.

A TPM result code is returned in ptm_res.

PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est

This command is used to reset the TPM's establishment flag.

The ptm_reset_est data structure looks as follows:

 struct ptm_reset_est {
    union {
        struct {
            uint8_t loc; /* locality to use */
        } req; /* request */
        struct {
            ptm_res tpm_result;
        } resp; /* response */
    } u;
 };

The locality in which the establishment flag is to be reset must be set in the loc field. Valid localities are in the range of 0 to 4.

A TPM result code is returned in the tpm_result field.

PTM_GET_STATEBLOB /  CMD_GET_STATEBLOB, ptm_getstate

This command is used to initiate the retrieval of one of the TPM's stateblobs.

The ptm_getstate data structure looks as follows:

 struct ptm_getstate {
    union {
        struct {
            uint32_t state_flags; /* may be: PTM_STATE_FLAG_DECRYPTED */
            uint32_t type;        /* which blob to pull */
            uint32_t offset;      /* offset from where to read */
        } req; /* request */
        struct {
            ptm_res tpm_result;
            uint32_t state_flags; /* may be: PTM_STATE_FLAG_ENCRYPTED */
            uint32_t totlength;   /* total length that will be transferred */
            uint32_t length;      /* number of bytes in following buffer */
            uint8_t  data[PTM_STATE_BLOB_SIZE];
        } resp; /* response */
    } u;
 };

In the request the state_flags field allows a user to set the PTM_STATE_FLAG_DECRYPT flag to retrieve decrypted TPM state in case the TPM's state was written in encrypted form.

The type field allows a user to choose one of the TPM's state blobs, and must be one of PTM_BLOB_TYPE_PERMANENT, PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.

The offset field indicates at what offset to read the data from. Subsequent state transfers must advance the offset field to the next byte to be read. If the read() interface is used the offset will be advanced automatically.

The response returns a TPM error code in the tpm_result field.

The state_flags field in the response indicates whether the returned blob is encrypted.

The totlength field indicates the total length of the state blob.

The length field indicates the number of valid bytes in the data field.

If necessary, subsequent state blob transfers must be done using this ioctl or using the read() call on the file descriptor. All state must be transferred before the TPM will accept commands again.

PTM_SET_STATEBLOB / CMD_SET_STATEBLOB, ptm_setstate

This command is used to transfer one of the TPM's stateblob to the TPM.

The ptm_setstate data structure looks as follows:

 struct ptm_setstate {
    union {
        struct {
            uint32_t state_flags; /* may be PTM_STATE_FLAG_ENCRYPTED */
            uint32_t type;        /* which blob to set */
            uint32_t length;      /* length of the data;
                                     use 0 on the first packet to
                                     transfer using write() */
            uint8_t data[PTM_STATE_BLOB_SIZE];
        } req; /* request */
        struct {
            ptm_res tpm_result;
        } resp; /* response */
    } u;
 };

The state_flags field indicates whether the provided state is encrypted. In case it is encrypted, a migration key must have been provided to the TPM for it to be able to decrypt the state.

The type field indicates which one of the TPM's state blobs is being set. It must be either one of PTM_BLOB_TYPE_PERMANENT, PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.

The length field indicates the number of bytes of state blob data in the data field. To transfer the state blob using the write() call, set the length to 0.

The response returns a TPM error code in the tpm_result field.

PTM_STOP / CMD_STOP, ptm_res

This command is used to stop the TPM. In contrast to a TPM shut down, the stopping of the TPM only halts its operations without terminating the TPM process. The TPM can restart operation with the PTM_INIT ioctl.

A TPM result code is returned in ptm_res.

PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig

This command is used to retrieve the TPM's current configuration.

The ptm_getconfig data structure looks as follows:

 struct ptm_getconfig {
    union {
        struct {
            ptm_res tpm_result;
            uint32_t flags;
        } resp; /* response */
    } u;
 };

A TPM result code is returned in the tpm_result field.

The flags field holds individual flags that indicate whether a file encryption key is used (PTM_CONFIG_FLAG_FILE_KEY) and whether a migration key is used (PTM_CONFIG_FLAG_MIGRATION_KEY).

CMD_SET_DATAFD, ptm_res

This command is only implemented for the control channel over UnixIO socket. It is used to establish the TPM command channel by transferring a socket file descriptor using the UnixIO socket's control channel and SCM_RIGHTS. See also sendmsg(2) and cmsg(3).

A TPM result code is returned in ptm_res.

CMD_SET_BUFFERSIZE, ptm_setbuffersize

This command allows a user to set and query for the buffer size that the TPM is using for input and output I/O buffers.

The ptm_setbuffersize data structure looks as follows:

 struct ptm_setbuffersize {
    union {
        struct {
            uint32_t buffersize; /* 0 to query for current buffer size */
        } req; /* request */
        struct {
            ptm_res tpm_result;
            uint32_t buffersize; /* buffer size in use */
            uint32_t minsize; /* min. supported buffer size */
            uint32_t maxsize; /* max. supported buffer size */
        } resp; /* response */
    } u;
 };

If a 0 is set in the buffer size of the request, the response will return the buffer size that is currently in use. Any other number will try to change the buffer size, but the TPM may adjust it to an allowed minimum or maximum. The minimum and maximum supported buffer sizes are returned in the response.

The buffersize can only be changed when the TPM is stopped. The currently used buffersize can be read at any time.

CMD_LOCK_STORAGE, ptm_lockstorage

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.

The ptm_lockstorage data structure looks as follows:

 struct ptm_lockstorage {
     union {
         struct {
             uint32_t retries; /* number of retries */
         } req; /* request */
         struct {
             ptm_res tpm_result;
         } resp; /* response */
     } u;
 };

A TPM result code is returned in the tpm_result field.

swtpm_ioctl(8), swtpm_cuse(8)