| .\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29) |
| .\" |
| .\" Standard preamble: |
| .\" ======================================================================== |
| .de Sp \" Vertical space (when we can't use .PP) |
| .if t .sp .5v |
| .if n .sp |
| .. |
| .de Vb \" Begin verbatim text |
| .ft CW |
| .nf |
| .ne \\$1 |
| .. |
| .de Ve \" End verbatim text |
| .ft R |
| .fi |
| .. |
| .\" Set up some character translations and predefined strings. \*(-- will |
| .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left |
| .\" double quote, and \*(R" will give a right double quote. \*(C+ will |
| .\" give a nicer C++. Capital omega is used to do unbreakable dashes and |
| .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, |
| .\" nothing in troff, for use with C<>. |
| .tr \(*W- |
| .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' |
| .ie n \{\ |
| . ds -- \(*W- |
| . ds PI pi |
| . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
| . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
| . ds L" "" |
| . ds R" "" |
| . ds C` "" |
| . ds C' "" |
| 'br\} |
| .el\{\ |
| . ds -- \|\(em\| |
| . ds PI \(*p |
| . ds L" `` |
| . ds R" '' |
| . ds C` |
| . ds C' |
| 'br\} |
| .\" |
| .\" Escape single quotes in literal strings from groff's Unicode transform. |
| .ie \n(.g .ds Aq \(aq |
| .el .ds Aq ' |
| .\" |
| .\" If the F register is turned on, we'll generate index entries on stderr for |
| .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| .\" entries marked with X<> in POD. Of course, you'll have to process the |
| .\" output yourself in some meaningful fashion. |
| .\" |
| .\" Avoid warning from groff about undefined register 'F'. |
| .de IX |
| .. |
| .nr rF 0 |
| .if \n(.g .if rF .nr rF 1 |
| .if (\n(rF:(\n(.g==0)) \{ |
| . if \nF \{ |
| . de IX |
| . tm Index:\\$1\t\\n%\t"\\$2" |
| .. |
| . if !\nF==2 \{ |
| . nr % 0 |
| . nr F 2 |
| . \} |
| . \} |
| .\} |
| .rr rF |
| .\" |
| .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). |
| .\" Fear. Run. Save yourself. No user-serviceable parts. |
| . \" fudge factors for nroff and troff |
| .if n \{\ |
| . ds #H 0 |
| . ds #V .8m |
| . ds #F .3m |
| . ds #[ \f1 |
| . ds #] \fP |
| .\} |
| .if t \{\ |
| . ds #H ((1u-(\\\\n(.fu%2u))*.13m) |
| . ds #V .6m |
| . ds #F 0 |
| . ds #[ \& |
| . ds #] \& |
| .\} |
| . \" simple accents for nroff and troff |
| .if n \{\ |
| . ds ' \& |
| . ds ` \& |
| . ds ^ \& |
| . ds , \& |
| . ds ~ ~ |
| . ds / |
| .\} |
| .if t \{\ |
| . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" |
| . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' |
| . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' |
| . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' |
| . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' |
| . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' |
| .\} |
| . \" troff and (daisy-wheel) nroff accents |
| .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' |
| .ds 8 \h'\*(#H'\(*b\h'-\*(#H' |
| .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] |
| .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' |
| .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' |
| .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] |
| .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] |
| .ds ae a\h'-(\w'a'u*4/10)'e |
| .ds Ae A\h'-(\w'A'u*4/10)'E |
| . \" corrections for vroff |
| .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' |
| .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' |
| . \" for low resolution devices (crt and lpr) |
| .if \n(.H>23 .if \n(.V>19 \ |
| \{\ |
| . ds : e |
| . ds 8 ss |
| . ds o a |
| . ds d- d\h'-1'\(ga |
| . ds D- D\h'-1'\(hy |
| . ds th \o'bp' |
| . ds Th \o'LP' |
| . ds ae ae |
| . ds Ae AE |
| .\} |
| .rm #[ #] #H #V #F C |
| .\" ======================================================================== |
| .\" |
| .IX Title "swtpm_ioctls 3" |
| .TH swtpm_ioctls 3 "2017-11-13" "swtpm" "" |
| .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| .\" way too many mistakes in technical documents. |
| .if n .ad l |
| .nh |
| .SH "NAME" |
| swtpm_ioctls \- Description of the ioctl's of the CUSE TPM (swtpm_cuse) |
| and control commands used by the control channel over socket interface. |
| .SH "SYNOPSYS" |
| .IX Header "SYNOPSYS" |
| \&\fB#include <tpm_ioctl.h>\fR |
| .SH "DESCRIPTION" |
| .IX Header "DESCRIPTION" |
| The \s-1CUSE TPM\s0 implements an ioctl interface on the \s-1CUSE TPM\s0's character device. |
| The ioctl's are used for out-of-band control of various \s-1TPM\s0 operations, |
| such as its intialization, resetting, and state migration. The control channel |
| over \s-1TCP\s0 or UnixIO sockets uses control commands for these operations. |
| .PP |
| 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 \s-1TPM\s0 error code in their response. Ioctl's are prefixed with |
| \&\fI\s-1PTM\s0\fR and control commands are prefixed with \fI\s-1CMD\s0\fR. |
| .PP |
| In case of the ioctl interface, the pointer to a command's data structure is |
| passed as the 2nd parameter to the \fIioctl()\fR function. The fields in the command's |
| data structure are to be fill out in host endianess format. |
| .PP |
| In case of control commands, the command code must be encoded as a 4 byte |
| interger preceding the command's data structure. Command code and data must be |
| written in big endian format. |
| .IP "\fB\s-1PTM_GET_CAPABILITY / CMD_GET_CAPABILITY,\s0 ptm_cap\fR" 4 |
| .IX Item "PTM_GET_CAPABILITY / CMD_GET_CAPABILITY, ptm_cap" |
| This ioctl allows the caller to check which ioctl's are implemented |
| by the \s-1CUSE TPM.\s0 The following is a list of capability flags that |
| may be set upon return: |
| .RS 4 |
| .IP "\fB\s-1PTM_CAP_INIT \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_INIT (since v0.1)" |
| The \s-1PTM_INIT\s0 ioctl or \s-1CMD_INIT\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_SHUTDOWN \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_SHUTDOWN (since v0.1)" |
| The \s-1PTM_SHUTDOWN\s0 ioctl or \s-1CMD_SHUTDOWN\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_GET_TPMESTABLISHED \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_GET_TPMESTABLISHED (since v0.1)" |
| The \s-1PTM_GET_TPMESTABLISHED\s0 ioctl or \s-1CMD_GET_TPMESTABLISHED\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_SET_LOCALITY \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_SET_LOCALITY (since v0.1)" |
| The \s-1PTM_SET_LOCALITY\s0 ioctl or \s-1CMD_SET_LOCALITY\s0 is supported. |
| .IP "\fB\s-1PTM_CAP_HASHING \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_HASHING (since v0.1)" |
| The \s-1PTM_HASH_START, PTM_HASH_DATA,\s0 and \s-1PTM_HASH_END\s0 ioctl's or |
| \&\s-1CMD_HASH_START, CMD_HASH_DATA, CMD_HASH_END\s0 commands are supported. |
| .IP "\fB\s-1PTM_CAP_CANCEL_TPM_CMD \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_CANCEL_TPM_CMD (since v0.1)" |
| The \s-1PTM_CANCEL_TPM_CMD\s0 ioctl or \s-1CMD_CANCEL_TPM_CMD\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_STORE_VOLATILE \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_STORE_VOLATILE (since v0.1)" |
| The \s-1PTM_STORE_VOLATILE\s0 ioctl or \s-1CMD_STORE_VOLATILE\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_RESET_TPMESTABLISHED \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_RESET_TPMESTABLISHED (since v0.1)" |
| The \s-1PTM_RESET_TPMESTABLISHED\s0 ioctl or \s-1CMD_RESET_TPMESTABLISHED\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_GET_STATEBLOB \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_GET_STATEBLOB (since v0.1)" |
| The \s-1PTM_GET_STATEBLOB\s0 ioctl or \s-1CMD_GET_STATEBLOB\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_SET_STATEBLOB \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_SET_STATEBLOB (since v0.1)" |
| The \s-1PTM_SET_STATEBLOB\s0 ioctl or \s-1CMD_SET_STATEBLOB\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_STOP \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_STOP (since v0.1)" |
| The \s-1PTM_STOP\s0 ioctl or \s-1CMD_STOP\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_GET_CONFIG \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_GET_CONFIG (since v0.1)" |
| The \s-1PTM_GET_CONFIG\s0 ioctl or \s-1CMD_GET_CONFIG\s0 command is supported. |
| .IP "\fB\s-1PTM_CAP_SET_DATAFD \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_CAP_SET_DATAFD (since v0.1)" |
| The \s-1CMD_SET_DATAFD\s0 command is supported. This command only applies to UnixIO |
| and there is no support for \s-1PTM_SET_DATAFD.\s0 |
| .IP "\fB\s-1PTM_SET_BUFFERSIZE \s0(since v0.1)\fR" 4 |
| .IX Item "PTM_SET_BUFFERSIZE (since v0.1)" |
| The \s-1PTM_SET_BUFFERSIZE\s0 ioctl or \s-1CMD_SET_BUFFERSIZE\s0 command is supported. |
| .RE |
| .RS 4 |
| .RE |
| .IP "\fB\s-1PTM_INIT / CMD_INIT,\s0 ptm_init\fR" 4 |
| .IX Item "PTM_INIT / CMD_INIT, ptm_init" |
| This ioctl must be used to initialize the \s-1TPM.\s0 It must be sent to the |
| \&\s-1TPM\s0 before any \s-1TPM\s0 command is sent. |
| .Sp |
| The ptm_init data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& struct ptm_init { |
| \& union { |
| \& struct { |
| \& uint32_t init_flags; /* see definitions below */ |
| \& } req; /* request */ |
| \& struct { |
| \& ptm_res tpm_result; |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| The init_flags field in the request can be used to have the \s-1TPM\s0 |
| delete the volatile state upon startup (\fB\s-1PTM_INIT_FLAG_DELETE_VOLATILE\s0\fR). |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .IP "\fB\s-1PTM_SHUTDOWN / CMD_SHUTDOWN,\s0 ptm_res\fR" 4 |
| .IX Item "PTM_SHUTDOWN / CMD_SHUTDOWN, ptm_res" |
| This ioctl allows to shut down the \s-1TPM.\s0 |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED,\s0 ptm_est\fR" 4 |
| .IX Item "PTM_GET_TPMESTABLISHED / CMD_GET_TPMESTABLISHED, ptm_est" |
| This ioctl is used to check whether the \s-1TPM\s0 established flag is set. |
| .Sp |
| The tpm_est data structure looks as follows: |
| .Sp |
| .Vb 8 |
| \& struct ptm_est { |
| \& union { |
| \& struct { |
| \& ptm_res tpm_result; |
| \& unsigned char bit; /* TPM established bit */ |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .Sp |
| The status of the \s-1TPM\s0 establishment flag is returned in the |
| bit field. |
| .IP "\fB\s-1PTM_SET_LOCALITY / CMD_SET_LOCALITY,\s0 ptm_loc\fR" 4 |
| .IX Item "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. |
| .Sp |
| The ptm_loc data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& struct ptm_loc { |
| \& union { |
| \& struct { |
| \& uint8_t loc; /* locality to set */ |
| \& } req; /* request */ |
| \& struct { |
| \& ptm_res tpm_result; |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| The locality number must be set in the request's loc field. Valid |
| localities are in the range of 0 to 4. |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .IP "\fB\s-1PTM_HASH_START / CMD_HASH_START,\s0 ptm_res\fR" 4 |
| .IX Item "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 |
| \&\s-1TPM\s0 Interface (\s-1TPM TIS\s0). Subsequent write operations for transferring |
| data must be done with the \fB\s-1PTM_HASH_DATA\s0\fR ioctl. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_HASH_DATA / CMD_HASH_DATA,\s0 ptm_hdata\fR" 4 |
| .IX Item "PTM_HASH_DATA / CMD_HASH_DATA, ptm_hdata" |
| This command is used to transfer the data for the hash operation. |
| .Sp |
| The ptm_hdata structure looks as follows: |
| .Sp |
| .Vb 11 |
| \& struct ptm_hdata { |
| \& union { |
| \& struct { |
| \& uint32_t length; |
| \& uint8_t data[4096]; |
| \& } req; /* request */ |
| \& struct { |
| \& ptm_res tpm_result; |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| 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. |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .IP "\fB\s-1PTM_HASH_END / CMD_HASH_END,\s0 ptm_res\fR" 4 |
| .IX Item "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 \fB\s-1PTM_HASH_START\s0\fR ioctl. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_CANCEL_CMD / CMD_CANCEL_CMD,\s0 ptm_res\fR" 4 |
| .IX Item "PTM_CANCEL_CMD / CMD_CANCEL_CMD, ptm_res" |
| This command is used to cancel a \s-1TPM\s0 command. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_STORE_VOLATILE / CMD_STORE_VOLATILE,\s0 ptm_res\fR" 4 |
| .IX Item "PTM_STORE_VOLATILE / CMD_STORE_VOLATILE, ptm_res" |
| This command is used to trigger the \s-1TPM\s0 to store the volatile state into |
| a file. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED,\s0 ptm_reset_est\fR" 4 |
| .IX Item "PTM_RESET_ESTABLISHED / CMD_RESET_ESTABLISHED, ptm_reset_est" |
| This command is used to reset the \s-1TPM\s0's establishment flag. |
| .Sp |
| The ptm_reset_est data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& struct ptm_reset_est { |
| \& union { |
| \& struct { |
| \& uint8_t loc; /* locality to use */ |
| \& } req; /* request */ |
| \& struct { |
| \& ptm_res tpm_result; |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| 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. |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .IP "\fB\s-1PTM_GET_STATEBLOB / CMD_GET_STATEBLOB,\s0 ptm_getstate\fR" 4 |
| .IX Item "PTM_GET_STATEBLOB / CMD_GET_STATEBLOB, ptm_getstate" |
| This command is used to initiate the retrieval of one of the \s-1TPM\s0's stateblobs. |
| .Sp |
| The ptm_getstate data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& 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; |
| \& }; |
| .Ve |
| .Sp |
| In the request the state_flags field allows to set the |
| \&\fB\s-1PTM_STATE_FLAG_DECRYPT\s0\fR flag to retrieve decrypted \s-1TPM\s0 state in case |
| the \s-1TPM\s0's state was written in encrypted form. |
| .Sp |
| The type field allows to choose one of the \s-1TPM\s0's state blobs, and must be |
| one of \fB\s-1PTM_BLOB_TYPE_PERMANENT\s0\fR, \fB\s-1PTM_BLOB_TYPE_VOLATILE\s0\fR, and |
| \&\fB\s-1PTM_BLOB_TYPE_SAVESTATE\s0\fR. |
| .Sp |
| 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 \fIread()\fR interface is used the offset will be advanced automatically. |
| .Sp |
| The response returns a \s-1TPM\s0 error code in the tpm_result field. |
| .Sp |
| The state_flags field in the response indicates whether the returned |
| blob is encrypted. |
| .Sp |
| The totlength field indicates the total length of the state blob. |
| .Sp |
| The length field indicates the number of valid bytes in the data field. |
| .Sp |
| If necessary, subsequent state blob transfers must be done using this |
| ioctl or using the \fIread()\fR call on the file descriptor. All state |
| must be transferred before the \s-1TPM\s0 will accept commands again. |
| .IP "\fB\s-1PTM_SET_STATEBLOB / CMD_SET_STATEBLOB,\s0 ptm_setstate\fR" 4 |
| .IX Item "PTM_SET_STATEBLOB / CMD_SET_STATEBLOB, ptm_setstate" |
| This command is used to transfer one of the \s-1TPM\s0's stateblob to the \s-1TPM.\s0 |
| .Sp |
| The ptm_setstate data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& 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; |
| \& }; |
| .Ve |
| .Sp |
| 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 |
| \&\s-1TPM\s0 for it to be able to decrypt the state. |
| .Sp |
| The type field indicates which one of the \s-1TPM\s0's state blobs is being set. |
| It must be either one of \fB\s-1PTM_BLOB_TYPE_PERMANENT\s0\fR, |
| \&\fB\s-1PTM_BLOB_TYPE_VOLATILE\s0\fR, and \fB\s-1PTM_BLOB_TYPE_SAVESTATE\s0\fR. |
| .Sp |
| The length field indicates the number of bytes of state blob data in the |
| data field. To transfer the state blob using the \fIwrite()\fR call, set the |
| length to 0. |
| .Sp |
| The response returns a \s-1TPM\s0 error code in the tpm_result field. |
| .IP "\fB\s-1PTM_STOP / CMD_STOP,\s0 ptm_res\fR" 4 |
| .IX Item "PTM_STOP / CMD_STOP, ptm_res" |
| This command is used to stop the \s-1TPM.\s0 In contrast to a \s-1TPM\s0 shut down, |
| the stopping of the \s-1TPM\s0 only halts its operations without terminating |
| the \s-1TPM\s0 process. The \s-1TPM\s0 can restart operation with the \fB\s-1PTM_INIT\s0\fR |
| ioctl. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1PTM_GET_CONFIG / CMD_GET_CONFIG,\s0 ptm_getconfig\fR" 4 |
| .IX Item "PTM_GET_CONFIG / CMD_GET_CONFIG, ptm_getconfig" |
| This command is used to retrieve the \s-1TPM\s0's current configuration. |
| .Sp |
| The ptm_getconfig data structure looks as follows: |
| .Sp |
| .Vb 8 |
| \& struct ptm_getconfig { |
| \& union { |
| \& struct { |
| \& ptm_res tpm_result; |
| \& uint32_t flags; |
| \& } resp; /* response */ |
| \& } u; |
| \& }; |
| .Ve |
| .Sp |
| A \s-1TPM\s0 result code is returned in the tpm_result field. |
| .Sp |
| The flags field holds individual flags that indicate whether a file |
| encryption key is used (\fB\s-1PTM_CONFIG_FLAG_FILE_KEY\s0\fR) |
| and whether a migration key is used |
| (\fB\s-1PTM_CONFIG_FLAG_MIGRATION_KEY\s0\fR). |
| .IP "\fB\s-1CMD_SET_DATAFD,\s0 ptm_res\fR" 4 |
| .IX Item "CMD_SET_DATAFD, ptm_res" |
| This command is only implemented for the control channel over UnixIO socket. |
| It is used to establish the \s-1TPM\s0 command channel by transferring a socket file |
| descriptor using the UnixIO socket's control channel and \fI\s-1SCM_RIGHTS\s0\fR. |
| See also \fB\f(BIsendmsg\fB\|(2)\fR and \fB\f(BIcmsg\fB\|(3)\fR. |
| .Sp |
| A \s-1TPM\s0 result code is returned in ptm_res. |
| .IP "\fB\s-1CMD_SET_BUFFERSIZE,\s0 ptm_setbuffersize\fR" 4 |
| .IX Item "CMD_SET_BUFFERSIZE, ptm_setbuffersize" |
| This command allows to set and query for the buffer size that the \s-1TPM\s0 is |
| using for input and output I/O buffers. |
| .Sp |
| The ptm_setbuffersize data structure looks as follows: |
| .Sp |
| .Vb 10 |
| \& 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; |
| \& }; |
| .Ve |
| .Sp |
| 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 \s-1TPM\s0 may adjust it to |
| an allowed minimum or maximum. The minimum and maximum supported |
| buffer sizes are returned in the response. |
| .Sp |
| The buffersize can only be changed when the \s-1TPM\s0 is stopped. The |
| currently used buffersize can be read at any time. |
| .SH "SEE ALSO" |
| .IX Header "SEE ALSO" |
| \&\fB\f(BIswtpm_ioctl\fB\|(8)\fR, \fB\f(BIswtpm_cuse\fB\|(8)\fR |