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_SET_BUFFERSIZE (since v0.1)
88               The PTM_SET_BUFFERSIZE ioctl or CMD_SET_BUFFERSIZE command is
89               supported.
90
91       PTM_INIT / CMD_INIT, ptm_init
92           This ioctl must be used to initialize the TPM. It must be sent to
93           the TPM before any TPM command is sent.
94
95           The ptm_init data structure looks as follows:
96
97            struct ptm_init {
98               union {
99                   struct {
100                       uint32_t init_flags; /* see definitions below */
101                   } req; /* request */
102                   struct {
103                       ptm_res tpm_result;
104                   } resp; /* response */
105               } u;
106            };
107
108           The init_flags field in the request can be used to have the TPM
109           delete the volatile state upon startup
110           (PTM_INIT_FLAG_DELETE_VOLATILE).
111
112           A TPM result code is returned in the tpm_result field.
113
114       PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res
115           This ioctl allows a user to shut down the TPM.
116
117           A TPM result code is returned in ptm_res.
118
119       PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est
120           This ioctl is used to check whether the TPM established flag is
121           set.
122
123           The tpm_est data structure looks as follows:
124
125            struct ptm_est {
126               union {
127                   struct {
128                       ptm_res tpm_result;
129                       unsigned char bit; /* TPM established bit */
130                   } resp; /* response */
131               } u;
132            };
133
134           A TPM result code is returned in the tpm_result field.
135
136           The status of the TPM establishment flag is returned in the bit
137           field.
138
139       PTM_SET_LOCALITY / CMD_SET_LOCALITY, ptm_loc
140           This ioctl is used to set the current locality. All subsequent
141           commands will be executed in this locality until the locality is
142           changed.
143
144           The ptm_loc data structure looks as follows:
145
146            struct ptm_loc {
147               union {
148                   struct {
149                       uint8_t loc; /* locality to set */
150                   } req; /* request */
151                   struct {
152                       ptm_res tpm_result;
153                   } resp; /* response */
154               } u;
155            };
156
157           The locality number must be set in the request's loc field. Valid
158           localities are in the range of 0 to 4.
159
160           A TPM result code is returned in the tpm_result field.
161
162       PTM_HASH_START / CMD_HASH_START, ptm_res
163           This ioctl is used to start the hash operation that is typically
164           initiated by writing into certain registers of locality 4 of the
165           TPM Interface (TPM TIS). Subsequent write operations for
166           transferring data must be done with the PTM_HASH_DATA ioctl.
167
168           A TPM result code is returned in ptm_res.
169
170       PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata
171           This command is used to transfer the data for the hash operation.
172
173           The ptm_hdata structure looks as follows:
174
175            struct ptm_hdata {
176               union {
177                   struct {
178                       uint32_t length;
179                       uint8_t data[4096];
180                   } req; /* request */
181                   struct {
182                       ptm_res tpm_result;
183                   } resp; /* response */
184               } u;
185            };
186
187           The length of the data is indicated in the length field with the
188           data in the data field. Up to 4096 bytes can be transferred in one
189           call.
190
191           A TPM result code is returned in the tpm_result field.
192
193       PTM_HASH_END / CMD_HASH_END, ptm_res
194           This command is used to indicate the end of a hash operation that
195           was started with the PTM_HASH_START ioctl.
196
197           A TPM result code is returned in ptm_res.
198
199       PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res
200           This command is used to cancel a TPM command.
201
202           A TPM result code is returned in ptm_res.
203
204       PTM_STORE_VOLATILE / CMD_STORE_VOLATILE, ptm_res
205           This command is used to trigger the TPM to store the volatile state
206           into a file.
207
208           A TPM result code is returned in ptm_res.
209
210       PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est
211           This command is used to reset the TPM's establishment flag.
212
213           The ptm_reset_est data structure looks as follows:
214
215            struct ptm_reset_est {
216               union {
217                   struct {
218                       uint8_t loc; /* locality to use */
219                   } req; /* request */
220                   struct {
221                       ptm_res tpm_result;
222                   } resp; /* response */
223               } u;
224            };
225
226           The locality in which the establishment flag is to be reset must be
227           set in the loc field. Valid localities are in the range of 0 to 4.
228
229           A TPM result code is returned in the tpm_result field.
230
231       PTM_GET_STATEBLOB /  CMD_GET_STATEBLOB, ptm_getstate
232           This command is used to initiate the retrieval of one of the TPM's
233           stateblobs.
234
235           The ptm_getstate data structure looks as follows:
236
237            struct ptm_getstate {
238               union {
239                   struct {
240                       uint32_t state_flags; /* may be: PTM_STATE_FLAG_DECRYPTED */
241                       uint32_t type;        /* which blob to pull */
242                       uint32_t offset;      /* offset from where to read */
243                   } req; /* request */
244                   struct {
245                       ptm_res tpm_result;
246                       uint32_t state_flags; /* may be: PTM_STATE_FLAG_ENCRYPTED */
247                       uint32_t totlength;   /* total length that will be transferred */
248                       uint32_t length;      /* number of bytes in following buffer */
249                       uint8_t  data[PTM_STATE_BLOB_SIZE];
250                   } resp; /* response */
251               } u;
252            };
253
254           In the request the state_flags field allows a user to set the
255           PTM_STATE_FLAG_DECRYPT flag to retrieve decrypted TPM state in case
256           the TPM's state was written in encrypted form.
257
258           The type field allows a user to choose one of the TPM's state
259           blobs, and must be one of PTM_BLOB_TYPE_PERMANENT,
260           PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.
261
262           The offset field indicates at what offset to read the data from.
263           Subsequent state transfers must advance the offset field to the
264           next byte to be read.  If the read() interface is used the offset
265           will be advanced automatically.
266
267           The response returns a TPM error code in the tpm_result field.
268
269           The state_flags field in the response indicates whether the
270           returned blob is encrypted.
271
272           The totlength field indicates the total length of the state blob.
273
274           The length field indicates the number of valid bytes in the data
275           field.
276
277           If necessary, subsequent state blob transfers must be done using
278           this ioctl or using the read() call on the file descriptor. All
279           state must be transferred before the TPM will accept commands
280           again.
281
282       PTM_SET_STATEBLOB / CMD_SET_STATEBLOB, ptm_setstate
283           This command is used to transfer one of the TPM's stateblob to the
284           TPM.
285
286           The ptm_setstate data structure looks as follows:
287
288            struct ptm_setstate {
289               union {
290                   struct {
291                       uint32_t state_flags; /* may be PTM_STATE_FLAG_ENCRYPTED */
292                       uint32_t type;        /* which blob to set */
293                       uint32_t length;      /* length of the data;
294                                                use 0 on the first packet to
295                                                transfer using write() */
296                       uint8_t data[PTM_STATE_BLOB_SIZE];
297                   } req; /* request */
298                   struct {
299                       ptm_res tpm_result;
300                   } resp; /* response */
301               } u;
302            };
303
304           The state_flags field indicates whether the provided state is
305           encrypted.  In case it is encrypted, a migration key must have been
306           provided to the TPM for it to be able to decrypt the state.
307
308           The type field indicates which one of the TPM's state blobs is
309           being set.  It must be either one of PTM_BLOB_TYPE_PERMANENT,
310           PTM_BLOB_TYPE_VOLATILE, and PTM_BLOB_TYPE_SAVESTATE.
311
312           The length field indicates the number of bytes of state blob data
313           in the data field. To transfer the state blob using the write()
314           call, set the length to 0.
315
316           The response returns a TPM error code in the tpm_result field.
317
318       PTM_STOP / CMD_STOP, ptm_res
319           This command is used to stop the TPM. In contrast to a TPM shut
320           down, the stopping of the TPM only halts its operations without
321           terminating the TPM process. The TPM can restart operation with the
322           PTM_INIT ioctl.
323
324           A TPM result code is returned in ptm_res.
325
326       PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig
327           This command is used to retrieve the TPM's current configuration.
328
329           The ptm_getconfig data structure looks as follows:
330
331            struct ptm_getconfig {
332               union {
333                   struct {
334                       ptm_res tpm_result;
335                       uint32_t flags;
336                   } resp; /* response */
337               } u;
338            };
339
340           A TPM result code is returned in the tpm_result field.
341
342           The flags field holds individual flags that indicate whether a file
343           encryption key is used (PTM_CONFIG_FLAG_FILE_KEY) and whether a
344           migration key is used (PTM_CONFIG_FLAG_MIGRATION_KEY).
345
346       CMD_SET_DATAFD, ptm_res
347           This command is only implemented for the control channel over
348           UnixIO socket.  It is used to establish the TPM command channel by
349           transferring a socket file descriptor using the UnixIO socket's
350           control channel and SCM_RIGHTS.  See also sendmsg(2) and cmsg(3).
351
352           A TPM result code is returned in ptm_res.
353
354       CMD_SET_BUFFERSIZE, ptm_setbuffersize
355           This command allows a user to set and query for the buffer size
356           that the TPM is using for input and output I/O buffers.
357
358           The ptm_setbuffersize data structure looks as follows:
359
360            struct ptm_setbuffersize {
361               union {
362                   struct {
363                       uint32_t buffersize; /* 0 to query for current buffer size */
364                   } req; /* request */
365                   struct {
366                       ptm_res tpm_result;
367                       uint32_t buffersize; /* buffer size in use */
368                       uint32_t minsize; /* min. supported buffer size */
369                       uint32_t maxsize; /* max. supported buffer size */
370                   } resp; /* response */
371               } u;
372            };
373
374           If a 0 is set in the buffer size of the request, the response will
375           return the buffer size that is currently in use. Any other number
376           will try to change the buffer size, but the TPM may adjust it to an
377           allowed minimum or maximum. The minimum and maximum supported
378           buffer sizes are returned in the response.
379
380           The buffersize can only be changed when the TPM is stopped. The
381           currently used buffersize can be read at any time.
382

SEE ALSO

384       swtpm_ioctl(8), swtpm_cuse(8)
385
386
387
388swtpm                             2021-11-09                   swtpm_ioctls(3)
Impressum