]>
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 '-' | |
2bc601bb | 167 | allows a user to skip the selection and activates all PCR banks. By default |
9f4d8af2 SB |
168 | the sha1 and sha256 banks are activated. |
169 | ||
e2951df7 SB |
170 | =item B<--swtpm_ioctl <executable>> |
171 | ||
172 | Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl | |
173 | in the PATH is used. | |
174 | ||
79edd90c SB |
175 | =item B<--tcsd-system-ps-file <file>> |
176 | ||
cc410ca9 | 177 | This option is deprecated and has no effect (since v0.4). |
79edd90c | 178 | |
3392e3ed | 179 | =item B<--rsa-keysize <keysize>> (since v0.4) |
6c5b7c2d SB |
180 | |
181 | This option allows to pass the size of a TPM 2 RSA EK key, such as 2048 | |
182 | or 3072. The supported keysizes for a TPM 2 can be queried for using | |
183 | the I<--print-capabilities> option. The default size is 2048 bits for | |
7dc24c2f SB |
184 | both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key |
185 | size is used. | |
6c5b7c2d | 186 | |
166d7b42 SB |
187 | =item B<--print-capabilities> (since v0.2) |
188 | ||
80d7bb48 SB |
189 | Print capabilities that were added to swtpm_setup after version 0.1. |
190 | The output may contain the following: | |
166d7b42 SB |
191 | |
192 | { | |
193 | "type": "swtpm_setup", | |
194 | "features": [ | |
195 | "cmdarg-keyfile-fd", | |
1974f2ce | 196 | "cmdarg-pwdfile-fd", |
78559edd | 197 | "cmdarg-write-ek-cert-files", |
2b607237 | 198 | "cmdarg-create-config-files", |
80d7bb48 | 199 | "tpm2-rsa-keysize-2048", |
cc410ca9 | 200 | "tpm2-rsa-keysize-3072", |
3eac2477 SB |
201 | "tpm12-not-need-root", |
202 | "tpm-1.2", | |
203 | "tpm-2.0" | |
55404e26 MAL |
204 | ], |
205 | "version": "0.7.0" | |
166d7b42 SB |
206 | } |
207 | ||
55404e26 MAL |
208 | The version field is available since 0.7. |
209 | ||
166d7b42 SB |
210 | The meaning of the feature verbs is as follows: |
211 | ||
212 | =over 4 | |
213 | ||
214 | =item B<cmdarg-key-fd> | |
215 | ||
216 | The I<--keyfile-fd> option is supported. | |
217 | ||
218 | =item B<cmdarg-pwd-fd> | |
219 | ||
220 | The I<--pwdfile-fd> option is supported. | |
221 | ||
78559edd SB |
222 | =item B<cmdarg-write-ek-cert-files> |
223 | ||
2b607237 SB |
224 | The I<--write-ek-cert-files> option is supported. |
225 | ||
226 | =item B<cmdarg-create-config-files> | |
227 | ||
228 | The I<--create-config-files> option is supported. | |
78559edd | 229 | |
80d7bb48 SB |
230 | =item B<tpm2-rsa-keysize-2048, ...> |
231 | ||
232 | The shown RSA key sizes are supported for a TPM 2's EK key. If none of the | |
233 | tpm2-rsa-keysize verbs is shown then only RSA 2048 bit keys are supported. | |
234 | ||
cc410ca9 SB |
235 | =item B<tpm12-not-need-root> (since 0.4.0) |
236 | ||
237 | This option implies that any user can setup a TPM 1.2. Previously only root | |
238 | or the 'tss' user, depending on configuration and availability of this account, | |
239 | could do that. | |
240 | ||
3eac2477 SB |
241 | =item B<tpm-1.2> (since 0.7) |
242 | ||
243 | TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support). | |
244 | ||
245 | ==item B<tpm-2.0> (since 0.7) | |
246 | ||
247 | TPM 2 setup is supported (libtpms is compiled with TPM 2 support). | |
248 | ||
166d7b42 SB |
249 | =back |
250 | ||
78559edd SB |
251 | =item B<--write-ek-cert-files <directory>> |
252 | ||
253 | This option causes endorsement key (EK) files to be written into the provided | |
254 | directory. The files contain the DER-formatted EKs that were written into the | |
255 | NVRAM locations of the TPM 1.2 or TPM 2. The EK files have the filename pattern | |
256 | of ek-<key type>.crt. Example for filenames are ek-rsa2048.crt, ek-rsa3072.crt, | |
257 | and ek-secp384r1.crt. | |
258 | ||
259 | The keys that are written for a TPM 2 may change over time as the default | |
260 | strength of the EK keys changes. This means that one should look for all | |
261 | files with the above filename pattern when looking for the EKs. | |
262 | ||
2b607237 SB |
263 | =item B<--create-config-files [[overwrite][,root]]> |
264 | ||
265 | This option allows a user to create config files for swtpm_setup and | |
266 | swtpm-localca under the $XDG_CONFIG_HOME or $HOME/.config directories. | |
267 | ||
268 | The meaning of the options is as follows: | |
269 | ||
270 | =over 4 | |
271 | ||
272 | ==item B<overwrite> | |
273 | ||
274 | Overwrite any existing config files. | |
275 | ||
276 | ==item B<root> | |
277 | ||
278 | Create the config files even under the root account. These config files | |
279 | may then shadow any other existing config files, such as | |
280 | /etc/swtpm-localca.conf for example. | |
281 | ||
282 | =back | |
283 | ||
e46a2b66 SB |
284 | =item B<--help, -h> |
285 | ||
286 | Display the help screen | |
287 | ||
288 | =back | |
289 | ||
026a2efe SB |
290 | =head1 EXAMPLE USAGE |
291 | ||
292 | To simulate manufacturing of a TPM, one would typically run the following command: | |
293 | ||
294 | #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \ | |
295 | --create-ek-cert --create-platform-cert --lock-nvram | |
296 | ||
cc410ca9 | 297 | Note: since v0.4 TPM 1.2 setup does not require root rights anymore. |
55caf371 | 298 | |
cc410ca9 | 299 | Any user can also simulate the manufacturing of a TPM using the |
3d5ae5e1 | 300 | swtpm_localca utility. The following example assumes that the user has |
55caf371 SB |
301 | set the environment variable XDG_CONFIG_HOME as follows (using bash for |
302 | example): | |
303 | ||
304 | export XDG_CONFIG_HOME=~/.config | |
305 | ||
306 | Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory | |
307 | Specification. | |
308 | ||
309 | The following configuration files need to be created: | |
310 | ||
311 | ~/.config/swtpm_setup.conf: | |
312 | ||
313 | # Program invoked for creating certificates | |
314 | create_certs_tool= /usr/share/swtpm/swtpm-localca | |
315 | create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf | |
316 | create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options | |
317 | ||
318 | ~/.config/swtpm-localca.conf: | |
319 | ||
320 | statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca | |
321 | signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem | |
322 | issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem | |
323 | certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial | |
324 | ||
325 | ~/.config/swtpm-localca.options: | |
326 | ||
327 | --platform-manufacturer Fedora | |
328 | --platform-version 2.12 | |
329 | --platform-model QEMU | |
330 | ||
a12b09b1 SB |
331 | Note: The tool swtpm-create-user-config-files can be used to create such |
332 | files (with different content): | |
333 | ||
334 | #> /usr/share/swtpm/swtpm-create-user-config-files | |
335 | Writing /home/stefanb/.config/swtpm_setup.conf. | |
336 | Writing /home/stefanb/.config/swtpm-localca.conf. | |
337 | Writing /home/stefanb/.config/swtpm-localca.options. | |
338 | ||
55caf371 SB |
339 | The following commands now create a TPM 2 with an EK and platform |
340 | certificate. The state of the TPM 2 will be stored in the directory | |
341 | ${XDG_CONFIG_HOME}/mytpm1. | |
342 | ||
343 | #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1 | |
344 | #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \ | |
345 | --create-ek-cert --create-platform-cert --lock-nvram | |
346 | ||
347 | ||
e46a2b66 SB |
348 | =head1 SEE ALSO |
349 | ||
350 | B<swtpm_setup.conf> | |
351 | ||
352 | =head1 REPORTING BUGS | |
353 | ||
0dd19b92 | 354 | Report bugs to Stefan Berger <stefanb@linux.ibm.com> |