]>
Commit | Line | Data |
---|---|---|
f163b202 SB |
1 | =head1 NAME |
2 | ||
3 | swtpm | |
4 | ||
5 | =head1 SYNOPSIS | |
6 | ||
7 | B<swtpm socket [OPTIONS]> | |
8 | ||
29cfd0a4 SB |
9 | B<swtpm chardev [OPTIONS]> |
10 | ||
78c5f924 SB |
11 | B<swtpm cuse [OPTIONS]> |
12 | ||
f163b202 SB |
13 | =head1 DESCRIPTION |
14 | ||
15 | B<swtpm> implements a TPM software emulator built on libtpms. | |
29cfd0a4 | 16 | It provides access to TPM functionality over a TCP/IP socket interface |
78c5f924 SB |
17 | or it can listend for commands on a character device, or create a CUSE |
18 | (character device in userspace) interface for receiving of TPM commands. | |
f163b202 SB |
19 | |
20 | Unless corresponding command line parameters are used, the | |
29cfd0a4 | 21 | B<swtpm> socket version requires that the environment variable I<TPM_PORT> |
f163b202 SB |
22 | be set to the TCP/IP port the process is supposed to listen on for TPM |
23 | request messages. | |
24 | ||
bc525ccd | 25 | Similarly, the environment variable I<TPM_PATH> can be set and |
f163b202 | 26 | contain the name of a directory where the TPM can store its persistent |
bc525ccd | 27 | state into. |
f163b202 | 28 | |
29cfd0a4 | 29 | The B<swtpm> process can be gracefully terminated by sending a |
f163b202 SB |
30 | I<SIGTERM> signal to it. |
31 | ||
78c5f924 SB |
32 | The B<swtpm> cuse version requires root rights to start the TPM. |
33 | ||
29cfd0a4 SB |
34 | =head1 Options for socket interface |
35 | ||
f163b202 SB |
36 | The following options are supported if the I<socket> interface is chosen: |
37 | ||
38 | =over 4 | |
39 | ||
40 | =item B<-p|--port <port>> | |
41 | ||
42 | Use the given port rather than using the environment variable TPM_PORT. | |
43 | ||
29cfd0a4 SB |
44 | =item B<-t|--terminate> |
45 | ||
46 | Terminate the TPM after the client has closed the connection. | |
47 | ||
48 | =back | |
49 | ||
50 | ||
51 | =head1 Options for character device interface | |
52 | ||
78c5f924 | 53 | The following options are supported if the I<chardev> interface is chosen: |
29cfd0a4 SB |
54 | |
55 | =over 4 | |
56 | ||
57 | =item B<-c|--chardev <device path>> | |
58 | ||
59 | Use the given device to listen for TPM commands and send response on. | |
60 | ||
78c5f924 SB |
61 | =item B<--ctrl type=[unixio|tcp][,path=E<lt>pathE<gt>][,port=E<lt>portE<gt>][,fd=E<lt>filedescriptorE<gt>] > |
62 | ||
63 | This option adds a control channel to the TPM. The control channel can either use a UnixIO socket with | |
64 | a given I<path> or I<filedescriptor> or it can use a TCP socket on the given I<port> or I<filedescriptor>. | |
65 | ||
66 | The control channel enables out-of-band control of the TPM, such as resetting the TPM. | |
67 | ||
29cfd0a4 SB |
68 | =back |
69 | ||
70 | ||
78c5f924 | 71 | =head1 Options for the CUSE interface |
29cfd0a4 | 72 | |
78c5f924 | 73 | The following options are supported if the I<cuse> interface is chosen: |
29cfd0a4 SB |
74 | |
75 | =over 4 | |
76 | ||
78c5f924 | 77 | =item B<-n|--name <NAME>> |
f163b202 | 78 | |
78c5f924 SB |
79 | The TPM will use a device with the given name. A device with the given name |
80 | will be created in /dev. This is a mandatory option. | |
81 | ||
82 | =item B<-M|--maj <MAJOR>> | |
83 | ||
84 | Create the device with the given major number. | |
85 | ||
86 | =item B<-m|--min <MINOR>> | |
87 | ||
88 | Create the device with the given minor number. | |
89 | ||
90 | =item B<--migration-key file=E<lt>keyfileE<gt>[,format=E<lt>hex|binaryE<gt>][,mode=aes-cbc],[remove[=true|false]]> | |
91 | ||
92 | The availability of a migration key ensures that the state of the TPM | |
93 | will not be revealed in unencrypted form when | |
94 | the TPM state blobs are retreived through the ioctl interface. | |
95 | The migration key is not used for encrypting TPM state written to files, | |
96 | this is what the I<--key> parameter is used for. | |
97 | ||
98 | The migration key and the key used for encrypting the TPM state files may be the same. | |
99 | ||
100 | While the key for the TPM state files needs to stay with those files it encrypts, the | |
101 | migration key needs to stay with the TPM state blobs. If for example the state of the | |
102 | TPM is migrated between hosts in a data center, then the TPM migration key must be | |
103 | available at all the destinations, so in effect it may have to be a key shared across | |
104 | all machines in the datacenter. In contrast to that, the key used for encrypting the | |
105 | TPM state B<files> can be different for each TPM and need only be available | |
106 | on the host where the TPM state resides. | |
107 | ||
108 | The migration key enables the encryption of the TPM state blobs of the TPM. | |
109 | The keyfile must contain an AES key of supported size; currently only 128 bit (16 bytes) | |
110 | keys are supported. | |
111 | ||
112 | The key may be in binary format, in which case the file size must be 16 bytes. | |
113 | If the key is in hex format (default), the key may consist of 32 hex digits | |
114 | starting with an optional '0x'. | |
115 | ||
116 | The I<mode> parameter indicates which block chaining mode is to be used. | |
117 | Currently only aes-cbc is supported. | |
118 | ||
119 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
120 | has been read. | |
121 | ||
122 | =item B<--migration-key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc],[remove[=true|false]]> | |
123 | ||
124 | This variant of the migration key parameter allows to provide a passphrase in a file. | |
125 | A maximum of 32 bytes are read from the file and a key is derived from it using a | |
126 | SHA512 hash. Currently only 128 bit keys are supported. | |
127 | ||
128 | =back | |
129 | ||
130 | ||
131 | =head1 Options for socket and character device interfaces: | |
132 | ||
133 | The following options are supported by the socket and character device interfaces: | |
134 | ||
135 | =over 4 | |
f163b202 SB |
136 | |
137 | =item B<-f|--fd <fd>> | |
138 | ||
29cfd0a4 SB |
139 | Use the given socket file descriptor or character device file descriptor |
140 | for receiving TPM commands and sending responses. | |
141 | For the socket interface, this option automatically assumes -t. | |
f163b202 | 142 | |
78c5f924 SB |
143 | =item B<-d|--daemon> |
144 | ||
145 | Daemonize the process. | |
146 | ||
147 | =back | |
148 | ||
149 | ||
150 | =head1 Options for all interfaces | |
151 | ||
152 | The following options are support by all interfaces: | |
153 | ||
154 | =over 4 | |
155 | ||
156 | =item B<--tpmstate dir=E<lt>dirE<gt>> | |
157 | ||
158 | Use the given path rather than using the environment variable TPM_PATH. | |
159 | ||
f163b202 SB |
160 | =item B<--log fd=E<lt>fdE<gt>|file=E<lt>pathE<gt>> |
161 | ||
162 | Enable logging to a file given its file descriptor or its path. Use '-' for path to | |
163 | suppress the logging. | |
164 | ||
165 | =item B<--key file=E<lt>keyfileE<gt>[,format=E<lt>hex|binaryE<gt>][,mode=aes-cbc],[remove[=true|false]]> | |
166 | ||
167 | Enable encryption of the state files of the TPM. The keyfile must contain | |
168 | an AES key of supported size; currently only 128 bit (16 bytes) keys are | |
169 | supported. | |
170 | ||
171 | The key may be in binary format, in which case the file size must be 16 bytes. | |
172 | If the key is in hex format (default), the key may consist of 32 hex digits | |
173 | starting with an optional '0x'. | |
174 | ||
175 | The I<mode> parameter indicates which block chaining mode is to be used. | |
176 | Currently only aes-cbc is supported. | |
177 | ||
178 | The I<remove> parameter will attempt to remove the given keyfile once the key | |
179 | has been read. | |
180 | ||
181 | =item B<--key pwdfile=E<lt>passphrase fileE<gt>[,mode=aes-cbc],[remove[=true|false]]> | |
182 | ||
183 | This variant of the key parameter allows to provide a passphrase in a file. | |
184 | A maximum of 32 bytes are read from the file and a key is derived from it using a | |
185 | SHA512 hash. Currently only 128 bit keys are supported. | |
186 | ||
b2151737 SB |
187 | =item B<--pid file=E<lt>pidfileE<gt>> |
188 | ||
189 | This options allows to set the name of file where the process ID (pid) of the TPM | |
190 | will be written into. | |
191 | ||
bb420d74 SB |
192 | =item B<-r|--runas E<lt>ownerE<gt>> |
193 | ||
194 | Switch to the given user. This option can only be used when swtpm is started as root. | |
195 | ||
f163b202 SB |
196 | =item B<-h|--help> |
197 | ||
198 | Display usage info. | |
199 | ||
200 | =back | |
201 | ||
202 | ||
203 | =head1 SEE ALSO | |
204 | ||
78c5f924 | 205 | B<swtpm_bios>, B<swtpm_cuse> |