]>
Commit | Line | Data |
---|---|---|
e46a2b66 SB |
1 | =head1 NAME |
2 | ||
0dd19b92 | 3 | swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0 |
e46a2b66 SB |
4 | |
5 | =head1 SYNOPSIS | |
6 | ||
7 | B<swtpm_setup [OPTIONS]> | |
8 | ||
9 | =head1 DESCRIPTION | |
10 | ||
2bc601bb | 11 | B<swtpm_setup> is a tool that prepares the initial state for a libtpms-based |
e46a2b66 SB |
12 | TPM. |
13 | ||
14 | The following options are supported: | |
15 | ||
16 | =over 4 | |
17 | ||
18 | =item B<--runas <userid>> | |
19 | ||
aab15ef3 | 20 | Use this userid to run swtpm_setup as. Only 'root' can use this option. |
e46a2b66 SB |
21 | |
22 | =item B<--config <file>> | |
23 | ||
24 | Path to configuration file containing the tool to use for creating | |
25 | certificates; see also B<swtpm_setup.conf> | |
26 | ||
55caf371 | 27 | If this parameter is not provided, the default configuration file |
0dd19b92 SB |
28 | will be used. The search order for the default configuration file is |
29 | as follows. If the environment variable XDG_CONFIG_HOME is set, | |
30 | ${XDG_CONFIG_HOME}/swtpm_setup.conf will be used if available, otherwise if | |
31 | the environment variable HOME is set, ${HOME}/swtpm_setup.conf | |
32 | will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf | |
33 | will be used. | |
55caf371 | 34 | |
3aa53709 | 35 | =item B<--tpm-state <dir>> or B<--tpmstate <dir>> |
e46a2b66 | 36 | |
a4555cb8 SR |
37 | Path where the TPM's state will be written to; this is a mandatory argument. |
38 | Prefix with dir:// to use directory backend, or file:// to use linear file. | |
e46a2b66 | 39 | |
5007f2d0 | 40 | =item B<--tpm <path to executable>> |
e46a2b66 SB |
41 | |
42 | Path to the TPM executable; this is an optional argument and | |
5007f2d0 | 43 | by default the swtpm executable found in the PATH will be used. |
e46a2b66 | 44 | |
15226ad9 SB |
45 | =item B<--tpm2> |
46 | ||
47 | Do setup on a TPM 2; by default a TPM 1.2 is setup. | |
48 | ||
e46a2b66 SB |
49 | =item B<--createek> |
50 | ||
0dd19b92 | 51 | Create an endorsement key (EK). |
e46a2b66 | 52 | |
15226ad9 SB |
53 | =item B<--allow-signing> |
54 | ||
55 | Create an EK that can sign. This option requires --tpm2. | |
56 | ||
ef1407f5 SB |
57 | This option will create a non-standard EK. When re-creating the EK, TPM 2 |
58 | tools have to use the EK Template that is witten at an NV index corresponding | |
59 | to the created EK (e.g., NV index 0x01c00004 for RS 2048 EK). Otherwise the | |
60 | tool-created EK will not correspond to the actual key being used or the | |
61 | modulus shown in the EK certificate. | |
62 | ||
68332550 SB |
63 | Note that the TCG specification "EK Credential Profile For TPM Family 2.0; Level 0" |
64 | suggests in its section on "EK Usage" that "the Endorsement Key can be a | |
65 | created as a decryption or signing key." However, some platforms will | |
66 | not accept an EK as a signing key, or as a signing and encryption key, and | |
0dd19b92 | 67 | therefore this option should be used very carefully. |
68332550 | 68 | |
bab61563 SB |
69 | =item B<--decryption> |
70 | ||
71 | Create an EK that can be used for key encipherment. This is the default | |
72 | unless --allow-signing is passed. This option requires --tpm2. | |
73 | ||
08da93a9 SB |
74 | =item B<--ecc> |
75 | ||
76 | Create elliptic curve crypto (ECC) keys; by default RSA keys are generated. | |
77 | ||
e46a2b66 SB |
78 | =item B<--take-ownership> |
79 | ||
0dd19b92 | 80 | Take ownership; this option implies --createek. This option is only available for TPM 1.2. |
e46a2b66 SB |
81 | |
82 | =item B<--ownerpass <password>> | |
83 | ||
0dd19b92 | 84 | Provide custom owner password; default is 'ooo'. This option is only available for TPM 1.2. |
e46a2b66 SB |
85 | |
86 | =item B<--owner-well-known> | |
87 | ||
0dd19b92 SB |
88 | Use a password of all zeros (20 bytes of zeros) as the owner password. |
89 | This option is only available for TPM 1.2. | |
e46a2b66 SB |
90 | |
91 | =item B<--srkpass <password>> | |
92 | ||
0dd19b92 | 93 | Provide custom SRK password; default is 'sss'. This option is only available for TPM 1.2. |
e46a2b66 SB |
94 | |
95 | =item B<--srk-well-known> | |
96 | ||
0dd19b92 SB |
97 | Use a password of all zeros (20 bytes of zeros) as the SRK password. |
98 | This option is only available for TPM 1.2. | |
e46a2b66 SB |
99 | |
100 | =item B<--create-ek-cert> | |
101 | ||
0dd19b92 | 102 | Create an EK certificate; this implies --createek. |
e46a2b66 SB |
103 | |
104 | =item B<--create-platform-cert> | |
105 | ||
0dd19b92 | 106 | Create a platform certificate; this implies --create-ek-cert. |
e46a2b66 SB |
107 | |
108 | =item B<--lock-nvram> | |
109 | ||
0dd19b92 | 110 | Lock NVRAM access to all NVRAM locations that were written to. |
e46a2b66 SB |
111 | |
112 | =item B<--display> | |
113 | ||
114 | At the end display as much info as possible about the configuration | |
0dd19b92 | 115 | of the TPM. |
e46a2b66 SB |
116 | |
117 | =item B<--logfile <logfile>> | |
118 | ||
119 | The logfile to log to. By default logging goes to stdout and stderr. | |
120 | ||
121 | =item B<--keyfile <keyfile>> | |
122 | ||
123 | The key file contains an ASCII hex key consisting of 32 hex digits with an | |
124 | optional leading '0x'. This is the key to be used by the TPM emulator | |
125 | for encrypting the state of the TPM. | |
126 | ||
e36d7915 | 127 | =item B<--keyfile-fd <file descriptor>> |
ace4a684 | 128 | |
e36d7915 | 129 | Like B<--keyfile> but the key will be read from the file descriptor. |
ace4a684 | 130 | |
e46a2b66 SB |
131 | =item B<--pwdfile <passphrase file>> |
132 | ||
ace4a684 | 133 | The passphrase file contains a passphrase from which the TPM emulator |
755881ba | 134 | will derive the encryption key from and use the key for encrypting the TPM |
e46a2b66 SB |
135 | state. |
136 | ||
ace4a684 SB |
137 | =item B<--pwdfile-fd <file descriptor>> |
138 | ||
139 | Like B<--pwdfile> but the passphrase will be read from the file descriptor. | |
140 | ||
2e260468 SB |
141 | =item B<--ciper <cipher>> |
142 | ||
143 | The cipher may be either aes-cbc or aes-128-cbc for 128 bit AES encryption, | |
144 | or aes-256-cbc for 256 bit AES encryption. The same cipher must be used | |
145 | on the I<swtpm> command line later on. | |
146 | ||
eff9cc16 SB |
147 | =item B<--overwrite> |
148 | ||
149 | Overwrite existing TPM state. All previous state will be erased. | |
150 | If this option is not given and an existing state file is found, an error | |
151 | code is returned. | |
152 | ||
153 | =item B<--not-overwrite> | |
154 | ||
2bc601bb | 155 | Do not overwrite existing TPM state. If existing TPM state is found, the |
eff9cc16 SB |
156 | program ends without an error. |
157 | ||
a8bc74fd SB |
158 | =item B<--vmid <VM ID>> |
159 | ||
160 | Optional VM ID that can be used to keep track of certificates issued | |
026a2efe | 161 | for VMs (or containers). This parameter will be passed through to the tool |
a8bc74fd SB |
162 | used for creating the certificates and may be required by that tool. |
163 | ||
9f4d8af2 SB |
164 | =item B<--pcr-banks <PCR banks>> |
165 | ||
166 | Optional comma-separated list of PCR banks to activate. Providing '-' | |
a5cc0bf6 SB |
167 | allows a user to skip the selection and activates all PCR banks. |
168 | If this option is not provided, the I<swtpm_setup.conf> configuration | |
169 | file will be consulted for the active_pcr_banks entry. If no such | |
170 | entry is found then the default set of PCR banks will be activated. | |
171 | The default set of PCR banks can be determined using the I<--help> | |
172 | option. | |
9f4d8af2 | 173 | |
e2951df7 SB |
174 | =item B<--swtpm_ioctl <executable>> |
175 | ||
176 | Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl | |
177 | in the PATH is used. | |
178 | ||
79edd90c SB |
179 | =item B<--tcsd-system-ps-file <file>> |
180 | ||
cc410ca9 | 181 | This option is deprecated and has no effect (since v0.4). |
79edd90c | 182 | |
3392e3ed | 183 | =item B<--rsa-keysize <keysize>> (since v0.4) |
6c5b7c2d SB |
184 | |
185 | This option allows to pass the size of a TPM 2 RSA EK key, such as 2048 | |
186 | or 3072. The supported keysizes for a TPM 2 can be queried for using | |
187 | the I<--print-capabilities> option. The default size is 2048 bits for | |
7dc24c2f SB |
188 | both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key |
189 | size is used. | |
6c5b7c2d | 190 | |
25d4ac2d SB |
191 | =item B<--reconfigure> (since v0.7) |
192 | ||
193 | This option allows the reconfiguration of the active PCR banks of a | |
194 | TPM 2 using the I<--pcr-banks> option. | |
195 | ||
166d7b42 SB |
196 | =item B<--print-capabilities> (since v0.2) |
197 | ||
80d7bb48 SB |
198 | Print capabilities that were added to swtpm_setup after version 0.1. |
199 | The output may contain the following: | |
166d7b42 SB |
200 | |
201 | { | |
202 | "type": "swtpm_setup", | |
203 | "features": [ | |
204 | "cmdarg-keyfile-fd", | |
1974f2ce | 205 | "cmdarg-pwdfile-fd", |
78559edd | 206 | "cmdarg-write-ek-cert-files", |
2b607237 | 207 | "cmdarg-create-config-files", |
25d4ac2d | 208 | "cmdarg-reconfigure-pcr-banks", |
80d7bb48 | 209 | "tpm2-rsa-keysize-2048", |
cc410ca9 | 210 | "tpm2-rsa-keysize-3072", |
3eac2477 SB |
211 | "tpm12-not-need-root", |
212 | "tpm-1.2", | |
213 | "tpm-2.0" | |
55404e26 MAL |
214 | ], |
215 | "version": "0.7.0" | |
166d7b42 SB |
216 | } |
217 | ||
4641f19f | 218 | The version field is available since v0.7. |
55404e26 | 219 | |
166d7b42 SB |
220 | The meaning of the feature verbs is as follows: |
221 | ||
222 | =over 4 | |
223 | ||
4641f19f | 224 | =item B<cmdarg-key-fd> (since v0.2) |
166d7b42 SB |
225 | |
226 | The I<--keyfile-fd> option is supported. | |
227 | ||
4641f19f | 228 | =item B<cmdarg-pwd-fd> (since v0.2) |
166d7b42 SB |
229 | |
230 | The I<--pwdfile-fd> option is supported. | |
231 | ||
4641f19f | 232 | =item B<cmdarg-write-ek-cert-files> (since v0.7) |
78559edd | 233 | |
2b607237 SB |
234 | The I<--write-ek-cert-files> option is supported. |
235 | ||
4641f19f | 236 | =item B<cmdarg-create-config-files> (since v0.7) |
2b607237 SB |
237 | |
238 | The I<--create-config-files> option is supported. | |
78559edd | 239 | |
25d4ac2d SB |
240 | =item B<cmdarg-reconfigure-pcr-banks> (since v0.7) |
241 | ||
242 | The I<--reconfigure> option is supported and allows the reconfiguration of | |
243 | the active PCR banks. | |
244 | ||
4641f19f | 245 | =item B<tpm2-rsa-keysize-2048, ...> (since v0.4) |
80d7bb48 SB |
246 | |
247 | The shown RSA key sizes are supported for a TPM 2's EK key. If none of the | |
248 | tpm2-rsa-keysize verbs is shown then only RSA 2048 bit keys are supported. | |
249 | ||
4641f19f | 250 | =item B<tpm12-not-need-root> (since v0.4) |
cc410ca9 SB |
251 | |
252 | This option implies that any user can setup a TPM 1.2. Previously only root | |
253 | or the 'tss' user, depending on configuration and availability of this account, | |
254 | could do that. | |
255 | ||
4641f19f | 256 | =item B<tpm-1.2> (since v0.7) |
3eac2477 SB |
257 | |
258 | TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support). | |
259 | ||
4641f19f | 260 | =item B<tpm-2.0> (since v0.7) |
3eac2477 SB |
261 | |
262 | TPM 2 setup is supported (libtpms is compiled with TPM 2 support). | |
263 | ||
166d7b42 SB |
264 | =back |
265 | ||
4641f19f | 266 | =item B<--write-ek-cert-files <directory>> (since v0.7) |
78559edd SB |
267 | |
268 | This option causes endorsement key (EK) files to be written into the provided | |
269 | directory. The files contain the DER-formatted EKs that were written into the | |
270 | NVRAM locations of the TPM 1.2 or TPM 2. The EK files have the filename pattern | |
271 | of ek-<key type>.crt. Example for filenames are ek-rsa2048.crt, ek-rsa3072.crt, | |
272 | and ek-secp384r1.crt. | |
273 | ||
274 | The keys that are written for a TPM 2 may change over time as the default | |
275 | strength of the EK keys changes. This means that one should look for all | |
276 | files with the above filename pattern when looking for the EKs. | |
277 | ||
4641f19f | 278 | =item B<--create-config-files [[overwrite][,root][,skip-if-exist]]> (since v0.7) |
2b607237 | 279 | |
db61aedd | 280 | This option allows a user to create configuration files for swtpm_setup and |
2b607237 SB |
281 | swtpm-localca under the $XDG_CONFIG_HOME or $HOME/.config directories. |
282 | ||
db61aedd SB |
283 | The configuration files will not be created if any one of them already |
284 | exists and in this case the program will report the first file it finds | |
285 | and exit with an error code. | |
286 | ||
2b607237 SB |
287 | The meaning of the options is as follows: |
288 | ||
289 | =over 4 | |
290 | ||
db61aedd | 291 | =item B<overwrite> |
2b607237 | 292 | |
db61aedd | 293 | Overwrite any existing configuration files. |
2b607237 | 294 | |
db61aedd | 295 | =item B<root> |
2b607237 | 296 | |
db61aedd SB |
297 | Create the configuration files even under the root account. These |
298 | configuration files may then shadow any other existing configuration files, | |
299 | such as /etc/swtpm-localca.conf for example. | |
2b607237 | 300 | |
db61aedd | 301 | =item B<skip-if-exist> |
a7254fab | 302 | |
db61aedd SB |
303 | Do nothing if any one of the configuration files that would be created already |
304 | exists. The program will exit without error code. | |
a7254fab | 305 | |
2b607237 SB |
306 | =back |
307 | ||
db61aedd SB |
308 | Note: The case when a user is part of the group that is allowed to access |
309 | the default configuration files' paths is currently not handled. On many | |
310 | systems this may be the case when a user is part of the 'tss' group. In | |
311 | this case it is recommended that the user replace the swtpm-localca.conf | |
312 | created with this command with a symbolic link to /etc/swtpm-localca.conf. | |
313 | ||
e46a2b66 SB |
314 | =item B<--help, -h> |
315 | ||
316 | Display the help screen | |
317 | ||
318 | =back | |
319 | ||
026a2efe SB |
320 | =head1 EXAMPLE USAGE |
321 | ||
322 | To simulate manufacturing of a TPM, one would typically run the following command: | |
323 | ||
324 | #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \ | |
325 | --create-ek-cert --create-platform-cert --lock-nvram | |
326 | ||
cc410ca9 | 327 | Note: since v0.4 TPM 1.2 setup does not require root rights anymore. |
55caf371 | 328 | |
cc410ca9 | 329 | Any user can also simulate the manufacturing of a TPM using the |
3d5ae5e1 | 330 | swtpm_localca utility. The following example assumes that the user has |
55caf371 SB |
331 | set the environment variable XDG_CONFIG_HOME as follows (using bash for |
332 | example): | |
333 | ||
334 | export XDG_CONFIG_HOME=~/.config | |
335 | ||
336 | Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory | |
337 | Specification. | |
338 | ||
339 | The following configuration files need to be created: | |
340 | ||
341 | ~/.config/swtpm_setup.conf: | |
342 | ||
343 | # Program invoked for creating certificates | |
344 | create_certs_tool= /usr/share/swtpm/swtpm-localca | |
345 | create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf | |
346 | create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options | |
347 | ||
348 | ~/.config/swtpm-localca.conf: | |
349 | ||
350 | statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca | |
351 | signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem | |
352 | issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem | |
353 | certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial | |
354 | ||
355 | ~/.config/swtpm-localca.options: | |
356 | ||
357 | --platform-manufacturer Fedora | |
358 | --platform-version 2.12 | |
359 | --platform-model QEMU | |
360 | ||
a12b09b1 SB |
361 | Note: The tool swtpm-create-user-config-files can be used to create such |
362 | files (with different content): | |
363 | ||
364 | #> /usr/share/swtpm/swtpm-create-user-config-files | |
365 | Writing /home/stefanb/.config/swtpm_setup.conf. | |
366 | Writing /home/stefanb/.config/swtpm-localca.conf. | |
367 | Writing /home/stefanb/.config/swtpm-localca.options. | |
368 | ||
55caf371 SB |
369 | The following commands now create a TPM 2 with an EK and platform |
370 | certificate. The state of the TPM 2 will be stored in the directory | |
371 | ${XDG_CONFIG_HOME}/mytpm1. | |
372 | ||
373 | #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1 | |
374 | #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \ | |
375 | --create-ek-cert --create-platform-cert --lock-nvram | |
376 | ||
377 | ||
e46a2b66 SB |
378 | =head1 SEE ALSO |
379 | ||
380 | B<swtpm_setup.conf> | |
381 | ||
382 | =head1 REPORTING BUGS | |
383 | ||
0dd19b92 | 384 | Report bugs to Stefan Berger <stefanb@linux.ibm.com> |