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_CAP_SET_BUFFERSIZE (since v0.1)
88 The PTM_SET_BUFFERSIZE ioctl or CMD_SET_BUFFERSIZE command is
89 supported.
90 PTM_CAP_LOCK_STORAGE (since v0.8)
92 The PTM_LOCK_STORAGE ioctl or CMD_LOCK_STORAGE command is
93 supported.
94 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 The ptm_init data structure looks as follows:
100 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 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 A TPM result code is returned in the tpm_result field.
117 PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res
119 This ioctl allows a user to shut down the TPM.
120 A TPM result code is returned in ptm_res.
122 PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est
124 This ioctl is used to check whether the TPM established flag is
125 set.
126 The tpm_est data structure looks as follows:
128 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 A TPM result code is returned in the tpm_result field.
139 The status of the TPM establishment flag is returned in the bit
141 field.
142 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 The ptm_loc data structure looks as follows:
149 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 The locality number must be set in the request's loc field. Valid
162 localities are in the range of 0 to 4.
163 A TPM result code is returned in the tpm_result field.
165 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 A TPM result code is returned in ptm_res.
173 PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata
175 This command is used to transfer the data for the hash operation.
176 The ptm_hdata structure looks as follows:
178 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 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 A TPM result code is returned in the tpm_result field.
196 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 A TPM result code is returned in ptm_res.
202 PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res
204 This command is used to cancel a TPM command.
205 A TPM result code is returned in ptm_res.
207 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 A TPM result code is returned in ptm_res.
213 PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est
215 This command is used to reset the TPM's establishment flag.
216 The ptm_reset_est data structure looks as follows:
218 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 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 A TPM result code is returned in the tpm_result field.
234 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 The ptm_getstate data structure looks as follows:
240 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 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 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 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 The response returns a TPM error code in the tpm_result field.
272 The state_flags field in the response indicates whether the
274 returned blob is encrypted.
275 The totlength field indicates the total length of the state blob.
277 The length field indicates the number of valid bytes in the data
279 field.
280 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 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 The ptm_setstate data structure looks as follows:
291 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 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 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 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 The response returns a TPM error code in the tpm_result field.
321 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 A TPM result code is returned in ptm_res.
329 PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig
331 This command is used to retrieve the TPM's current configuration.
332 The ptm_getconfig data structure looks as follows:
334 struct ptm_getconfig {
336 union {
337 struct {
338 ptm_res tpm_result;
339 uint32_t flags;
340 } resp; /* response */
341 } u;
342 };
343 A TPM result code is returned in the tpm_result field.
345 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 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 A TPM result code is returned in ptm_res.
357 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 The ptm_setbuffersize data structure looks as follows:
363 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 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 The buffersize can only be changed when the TPM is stopped. The
385 currently used buffersize can be read at any time.
386 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 The ptm_lockstorage data structure looks as follows:
395 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 A TPM result code is returned in the tpm_result field.
408
410 swtpm_ioctl(8), swtpm_cuse(8)
411swtpm 2023-08-16 swtpm_ioctls(3)