1swtpm_ioctls(3)                                                swtpm_ioctls(3)
2
3
4

NAME

6       swtpm_ioctls - Description of the ioctl's of the CUSE TPM (swtpm_cuse)
7       and control commands used by the control channel over socket interface.
8

SYNOPSYS

10       #include <tpm_ioctl.h>
11

DESCRIPTION

13       The CUSE TPM implements an ioctl interface on the CUSE TPM's character
14       device.  The ioctl's are used for out-of-band control of various TPM
15       operations, such as its initialization, resetting, and state migration.
16       The control channel over TCP or UnixIO sockets uses control commands
17       for these operations.
18
19       The following is an enumeration of the supported ioctl's and control
20       commands, along with the names of the data structure types. All ioctl's
21       and control commands return a TPM error code in their response. Ioctl's
22       are prefixed with PTM and control commands are prefixed with CMD.
23
24       In case of the ioctl interface, the pointer to a command's data
25       structure is passed as the 2nd parameter to the ioctl() function. The
26       fields in the command's data structure are to be fill out in host
27       endianness format.
28
29       In case of control commands, the command code must be encoded as a 4
30       byte integer preceding the command's data structure. Command code and
31       data must be written in big endian format.
32
33       PTM_GET_CAPABILITY / CMD_GET_CAPABILITY, ptm_cap
34           This ioctl allows the caller to check which ioctl's are implemented
35           by the CUSE TPM. The following is a list of capability flags that
36           may be set upon return:
37
38           PTM_CAP_INIT (since v0.1)
39               The PTM_INIT ioctl or CMD_INIT command is supported.
40
41           PTM_CAP_SHUTDOWN (since v0.1)
42               The PTM_SHUTDOWN ioctl or CMD_SHUTDOWN command is supported.
43
44           PTM_CAP_GET_TPMESTABLISHED (since v0.1)
45               The PTM_GET_TPMESTABLISHED ioctl or CMD_GET_TPMESTABLISHED
46               command is supported.
47
48           PTM_CAP_SET_LOCALITY (since v0.1)
49               The PTM_SET_LOCALITY ioctl or CMD_SET_LOCALITY is supported.
50
51           PTM_CAP_HASHING (since v0.1)
52               The PTM_HASH_START, PTM_HASH_DATA, and PTM_HASH_END ioctl's or
53               CMD_HASH_START, CMD_HASH_DATA, CMD_HASH_END commands are
54               supported.
55
56           PTM_CAP_CANCEL_TPM_CMD (since v0.1)
57               The PTM_CANCEL_TPM_CMD ioctl or CMD_CANCEL_TPM_CMD command is
58               supported.
59
60           PTM_CAP_STORE_VOLATILE (since v0.1)
61               The PTM_STORE_VOLATILE ioctl or CMD_STORE_VOLATILE command is
62               supported.
63
64           PTM_CAP_RESET_TPMESTABLISHED (since v0.1)
65               The PTM_RESET_TPMESTABLISHED ioctl or CMD_RESET_TPMESTABLISHED
66               command is supported.
67
68           PTM_CAP_GET_STATEBLOB (since v0.1)
69               The PTM_GET_STATEBLOB ioctl or CMD_GET_STATEBLOB command is
70               supported.
71
72           PTM_CAP_SET_STATEBLOB (since v0.1)
73               The PTM_SET_STATEBLOB ioctl or CMD_SET_STATEBLOB command is
74               supported.
75
76           PTM_CAP_STOP (since v0.1)
77               The PTM_STOP ioctl or CMD_STOP command is supported.
78
79           PTM_CAP_GET_CONFIG (since v0.1)
80               The PTM_GET_CONFIG ioctl or CMD_GET_CONFIG command is
81               supported.
82
83           PTM_CAP_SET_DATAFD (since v0.1)
84               The CMD_SET_DATAFD command is supported. This command only
85               applies to UnixIO and there is no support for PTM_SET_DATAFD.
86
87           PTM_CAP_SET_BUFFERSIZE (since v0.1)
88               The PTM_SET_BUFFERSIZE ioctl or CMD_SET_BUFFERSIZE command is
89               supported.
90
91           PTM_CAP_LOCK_STORAGE (since v0.8)
92               The PTM_LOCK_STORAGE ioctl or CMD_LOCK_STORAGE command is
93               supported.
94
95       PTM_INIT / CMD_INIT, ptm_init
96           This ioctl must be used to initialize the TPM. It must be sent to
97           the TPM before any TPM command is sent.
98
99           The ptm_init data structure looks as follows:
100
101            struct ptm_init {
102               union {
103                   struct {
104                       uint32_t init_flags; /* see definitions below */
105                   } req; /* request */
106                   struct {
107                       ptm_res tpm_result;
108                   } resp; /* response */
109               } u;
110            };
111
112           The init_flags field in the request can be used to have the TPM
113           delete the volatile state upon startup
114           (PTM_INIT_FLAG_DELETE_VOLATILE).
115
116           A TPM result code is returned in the tpm_result field.
117
118       PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res
119           This ioctl allows a user to shut down the TPM.
120
121           A TPM result code is returned in ptm_res.
122
123       PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est
124           This ioctl is used to check whether the TPM established flag is
125           set.
126
127           The tpm_est data structure looks as follows:
128
129            struct ptm_est {
130               union {
131                   struct {
132                       ptm_res tpm_result;
133                       unsigned char bit; /* TPM established bit */
134                   } resp; /* response */
135               } u;
136            };
137
138           A TPM result code is returned in the tpm_result field.
139
140           The status of the TPM establishment flag is returned in the bit
141           field.
142
143       PTM_SET_LOCALITY / CMD_SET_LOCALITY, ptm_loc
144           This ioctl is used to set the current locality. All subsequent
145           commands will be executed in this locality until the locality is
146           changed.
147
148           The ptm_loc data structure looks as follows:
149
150            struct ptm_loc {
151               union {
152                   struct {
153                       uint8_t loc; /* locality to set */
154                   } req; /* request */
155                   struct {
156                       ptm_res tpm_result;
157                   } resp; /* response */
158               } u;
159            };
160
161           The locality number must be set in the request's loc field. Valid
162           localities are in the range of 0 to 4.
163
164           A TPM result code is returned in the tpm_result field.
165
166       PTM_HASH_START / CMD_HASH_START, ptm_res
167           This ioctl is used to start the hash operation that is typically
168           initiated by writing into certain registers of locality 4 of the
169           TPM Interface (TPM TIS). Subsequent write operations for
170           transferring data must be done with the PTM_HASH_DATA ioctl.
171
172           A TPM result code is returned in ptm_res.
173
174       PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata
175           This command is used to transfer the data for the hash operation.
176
177           The ptm_hdata structure looks as follows:
178
179            struct ptm_hdata {
180               union {
181                   struct {
182                       uint32_t length;
183                       uint8_t data[4096];
184                   } req; /* request */
185                   struct {
186                       ptm_res tpm_result;
187                   } resp; /* response */
188               } u;
189            };
190
191           The length of the data is indicated in the length field with the
192           data in the data field. Up to 4096 bytes can be transferred in one
193           call.
194
195           A TPM result code is returned in the tpm_result field.
196
197       PTM_HASH_END / CMD_HASH_END, ptm_res
198           This command is used to indicate the end of a hash operation that
199           was started with the PTM_HASH_START ioctl.
200
201           A TPM result code is returned in ptm_res.
202
203       PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res
204           This command is used to cancel a TPM command.
205
206           A TPM result code is returned in ptm_res.
207
208       PTM_STORE_VOLATILE / CMD_STORE_VOLATILE, ptm_res
209           This command is used to trigger the TPM to store the volatile state
210           into a file.
211
212           A TPM result code is returned in ptm_res.
213
214       PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est
215           This command is used to reset the TPM's establishment flag.
216
217           The ptm_reset_est data structure looks as follows:
218
219            struct ptm_reset_est {
220               union {
221                   struct {
222                       uint8_t loc; /* locality to use */
223                   } req; /* request */
224                   struct {
225                       ptm_res tpm_result;
226                   } resp; /* response */
227               } u;
228            };
229
230           The locality in which the establishment flag is to be reset must be
231           set in the loc field. Valid localities are in the range of 0 to 4.
232
233           A TPM result code is returned in the tpm_result field.
234
235       PTM_GET_STATEBLOB /  CMD_GET_STATEBLOB, ptm_getstate
236           This command is used to initiate the retrieval of one of the TPM's
237           stateblobs.
238
239           The ptm_getstate data structure looks as follows:
240
241            struct ptm_getstate {
242               union {
243                   struct {
244                       uint32_t state_flags; /* may be: PTM_STATE_FLAG_DECRYPTED */
245                       uint32_t type;        /* which blob to pull */
246                       uint32_t offset;      /* offset from where to read */
247                   } req; /* request */
248                   struct {
249                       ptm_res tpm_result;
250                       uint32_t state_flags; /* may be: PTM_STATE_FLAG_ENCRYPTED */
251                       uint32_t totlength;   /* total length that will be transferred */
252                       uint32_t length;      /* number of bytes in following buffer */
253                       uint8_t  data[PTM_STATE_BLOB_SIZE];
254                   } resp; /* response */
255               } u;
256            };
257
258           In the request the state_flags field allows a user to set the
259           PTM_STATE_FLAG_DECRYPT flag to retrieve decrypted TPM state in case
260           the TPM's state was written in encrypted form.
261
262           The type field allows a user to choose one of the TPM's state
263           blobs, and must be one of PTM_BLOB_TYPE_PERMANENT,
264           PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.
265
266           The offset field indicates at what offset to read the data from.
267           Subsequent state transfers must advance the offset field to the
268           next byte to be read.  If the read() interface is used the offset
269           will be advanced automatically.
270
271           The response returns a TPM error code in the tpm_result field.
272
273           The state_flags field in the response indicates whether the
274           returned blob is encrypted.
275
276           The totlength field indicates the total length of the state blob.
277
278           The length field indicates the number of valid bytes in the data
279           field.
280
281           If necessary, subsequent state blob transfers must be done using
282           this ioctl or using the read() call on the file descriptor. All
283           state must be transferred before the TPM will accept commands
284           again.
285
286       PTM_SET_STATEBLOB / CMD_SET_STATEBLOB, ptm_setstate
287           This command is used to transfer one of the TPM's stateblob to the
288           TPM.
289
290           The ptm_setstate data structure looks as follows:
291
292            struct ptm_setstate {
293               union {
294                   struct {
295                       uint32_t state_flags; /* may be PTM_STATE_FLAG_ENCRYPTED */
296                       uint32_t type;        /* which blob to set */
297                       uint32_t length;      /* length of the data;
298                                                use 0 on the first packet to
299                                                transfer using write() */
300                       uint8_t data[PTM_STATE_BLOB_SIZE];
301                   } req; /* request */
302                   struct {
303                       ptm_res tpm_result;
304                   } resp; /* response */
305               } u;
306            };
307
308           The state_flags field indicates whether the provided state is
309           encrypted.  In case it is encrypted, a migration key must have been
310           provided to the TPM for it to be able to decrypt the state.
311
312           The type field indicates which one of the TPM's state blobs is
313           being set.  It must be either one of PTM_BLOB_TYPE_PERMANENT,
314           PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.
315
316           The length field indicates the number of bytes of state blob data
317           in the data field. To transfer the state blob using the write()
318           call, set the length to 0.
319
320           The response returns a TPM error code in the tpm_result field.
321
322       PTM_STOP / CMD_STOP, ptm_res
323           This command is used to stop the TPM. In contrast to a TPM shut
324           down, the stopping of the TPM only halts its operations without
325           terminating the TPM process. The TPM can restart operation with the
326           PTM_INIT ioctl.
327
328           A TPM result code is returned in ptm_res.
329
330       PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig
331           This command is used to retrieve the TPM's current configuration.
332
333           The ptm_getconfig data structure looks as follows:
334
335            struct ptm_getconfig {
336               union {
337                   struct {
338                       ptm_res tpm_result;
339                       uint32_t flags;
340                   } resp; /* response */
341               } u;
342            };
343
344           A TPM result code is returned in the tpm_result field.
345
346           The flags field holds individual flags that indicate whether a file
347           encryption key is used (PTM_CONFIG_FLAG_FILE_KEY) and whether a
348           migration key is used (PTM_CONFIG_FLAG_MIGRATION_KEY).
349
350       CMD_SET_DATAFD, ptm_res
351           This command is only implemented for the control channel over
352           UnixIO socket.  It is used to establish the TPM command channel by
353           transferring a socket file descriptor using the UnixIO socket's
354           control channel and SCM_RIGHTS.  See also sendmsg(2) and cmsg(3).
355
356           A TPM result code is returned in ptm_res.
357
358       CMD_SET_BUFFERSIZE, ptm_setbuffersize
359           This command allows a user to set and query for the buffer size
360           that the TPM is using for input and output I/O buffers.
361
362           The ptm_setbuffersize data structure looks as follows:
363
364            struct ptm_setbuffersize {
365               union {
366                   struct {
367                       uint32_t buffersize; /* 0 to query for current buffer size */
368                   } req; /* request */
369                   struct {
370                       ptm_res tpm_result;
371                       uint32_t buffersize; /* buffer size in use */
372                       uint32_t minsize; /* min. supported buffer size */
373                       uint32_t maxsize; /* max. supported buffer size */
374                   } resp; /* response */
375               } u;
376            };
377
378           If a 0 is set in the buffer size of the request, the response will
379           return the buffer size that is currently in use. Any other number
380           will try to change the buffer size, but the TPM may adjust it to an
381           allowed minimum or maximum. The minimum and maximum supported
382           buffer sizes are returned in the response.
383
384           The buffersize can only be changed when the TPM is stopped. The
385           currently used buffersize can be read at any time.
386
387       CMD_LOCK_STORAGE, ptm_lockstorage
388           Lock the storage and retry a given number of times with 10ms delay
389           in between.  Locking the storage may be necessary to do after the
390           state of the TPM has been migrated out and the lock on the storage
391           has been released when the 'savestate' blob was received and now
392           the storage should be locked again.
393
394           The ptm_lockstorage data structure looks as follows:
395
396            struct ptm_lockstorage {
397                union {
398                    struct {
399                        uint32_t retries; /* number of retries */
400                    } req; /* request */
401                    struct {
402                        ptm_res tpm_result;
403                    } resp; /* reponse */
404                } u;
405            };
406
407           A TPM result code is returned in the tpm_result field.
408

SEE ALSO

410       swtpm_ioctl(8), swtpm_cuse(8)
411
412
413
414swtpm                             2023-08-16                   swtpm_ioctls(3)
Impressum