1swtpm_ioctls(3) swtpm_ioctls(3)
2
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
10 #include <tpm_ioctl.h>
11
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 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 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 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 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 PTM_CAP_INIT (since v0.1)
39 The PTM_INIT ioctl or CMD_INIT command is supported.
40 PTM_CAP_SHUTDOWN (since v0.1)
42 The PTM_SHUTDOWN ioctl or CMD_SHUTDOWN command is supported.
43 PTM_CAP_GET_TPMESTABLISHED (since v0.1)
45 The PTM_GET_TPMESTABLISHED ioctl or CMD_GET_TPMESTABLISHED
46 command is supported.
47 PTM_CAP_SET_LOCALITY (since v0.1)
49 The PTM_SET_LOCALITY ioctl or CMD_SET_LOCALITY is supported.
50 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 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 PTM_CAP_STORE_VOLATILE (since v0.1)
61 The PTM_STORE_VOLATILE ioctl or CMD_STORE_VOLATILE command is
62 supported.
63 PTM_CAP_RESET_TPMESTABLISHED (since v0.1)
65 The PTM_RESET_TPMESTABLISHED ioctl or CMD_RESET_TPMESTABLISHED
66 command is supported.
67 PTM_CAP_GET_STATEBLOB (since v0.1)
69 The PTM_GET_STATEBLOB ioctl or CMD_GET_STATEBLOB command is
70 supported.
71 PTM_CAP_SET_STATEBLOB (since v0.1)
73 The PTM_SET_STATEBLOB ioctl or CMD_SET_STATEBLOB command is
74 supported.
75 PTM_CAP_STOP (since v0.1)
77 The PTM_STOP ioctl or CMD_STOP command is supported.
78 PTM_CAP_GET_CONFIG (since v0.1)
80 The PTM_GET_CONFIG ioctl or CMD_GET_CONFIG command is
81 supported.
82 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 PTM_SET_BUFFERSIZE (since v0.1)
88 The PTM_SET_BUFFERSIZE ioctl or CMD_SET_BUFFERSIZE command is
89 supported.
90 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 The ptm_init data structure looks as follows:
96 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 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 A TPM result code is returned in the tpm_result field.
113 PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res
115 This ioctl allows a user to shut down the TPM.
116 A TPM result code is returned in ptm_res.
118 PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est
120 This ioctl is used to check whether the TPM established flag is
121 set.
122 The tpm_est data structure looks as follows:
124 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 A TPM result code is returned in the tpm_result field.
135 The status of the TPM establishment flag is returned in the bit
137 field.
138 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 The ptm_loc data structure looks as follows:
145 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 The locality number must be set in the request's loc field. Valid
158 localities are in the range of 0 to 4.
159 A TPM result code is returned in the tpm_result field.
161 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 A TPM result code is returned in ptm_res.
169 PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata
171 This command is used to transfer the data for the hash operation.
172 The ptm_hdata structure looks as follows:
174 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 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 A TPM result code is returned in the tpm_result field.
192 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 A TPM result code is returned in ptm_res.
198 PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res
200 This command is used to cancel a TPM command.
201 A TPM result code is returned in ptm_res.
203 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 A TPM result code is returned in ptm_res.
209 PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est
211 This command is used to reset the TPM's establishment flag.
212 The ptm_reset_est data structure looks as follows:
214 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 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 A TPM result code is returned in the tpm_result field.
230 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 The ptm_getstate data structure looks as follows:
236 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 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 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 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 The response returns a TPM error code in the tpm_result field.
268 The state_flags field in the response indicates whether the
270 returned blob is encrypted.
271 The totlength field indicates the total length of the state blob.
273 The length field indicates the number of valid bytes in the data
275 field.
276 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 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 The ptm_setstate data structure looks as follows:
287 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 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 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 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 The response returns a TPM error code in the tpm_result field.
317 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 A TPM result code is returned in ptm_res.
325 PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig
327 This command is used to retrieve the TPM's current configuration.
328 The ptm_getconfig data structure looks as follows:
330 struct ptm_getconfig {
332 union {
333 struct {
334 ptm_res tpm_result;
335 uint32_t flags;
336 } resp; /* response */
337 } u;
338 };
339 A TPM result code is returned in the tpm_result field.
341 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 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 A TPM result code is returned in ptm_res.
353 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 The ptm_setbuffersize data structure looks as follows:
359 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 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 The buffersize can only be changed when the TPM is stopped. The
381 currently used buffersize can be read at any time.
382
384 swtpm_ioctl(8), swtpm_cuse(8)
385swtpm 2022-07-23 swtpm_ioctls(3)