3 swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0
7 B<swtpm_setup [OPTIONS]>
11 B<swtpm_setup> is a tool that prepares the initial state for a libtpms-based
14 The following options are supported:
18 =item B<--runas <userid>>
20 Use this userid to run swtpm_setup as. Only 'root' can use this option.
22 =item B<--config <file>>
24 Path to configuration file containing the tool to use for creating
25 certificates; see also B<swtpm_setup.conf>
27 If this parameter is not provided, the default configuration file
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}/.config/swtpm_setup.conf
32 will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf
35 =item B<--tpm-state <dir>> or B<--tpmstate <dir>>
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.
40 =item B<--tpm <path to executable>>
42 Path to the TPM executable; this is an optional argument and
43 by default the swtpm executable found in the PATH will be used.
47 Do setup on a TPM 2; by default a TPM 1.2 is setup.
51 Create an endorsement key (EK).
53 =item B<--allow-signing>
55 Create an EK that can sign. This option requires --tpm2.
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.
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
67 therefore this option should be used very carefully.
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.
76 Create elliptic curve crypto (ECC) keys; by default RSA keys are generated.
78 =item B<--take-ownership>
80 Take ownership; this option implies --createek. This option is only available for TPM 1.2.
82 =item B<--ownerpass <password>>
84 Provide custom owner password; default is 'ooo'. This option is only available for TPM 1.2.
86 =item B<--owner-well-known>
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.
91 =item B<--srkpass <password>>
93 Provide custom SRK password; default is 'sss'. This option is only available for TPM 1.2.
95 =item B<--srk-well-known>
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.
100 =item B<--create-ek-cert>
102 Create an EK certificate; this implies --createek.
104 =item B<--create-platform-cert>
106 Create a platform certificate; this implies --create-ek-cert.
108 =item B<--lock-nvram>
110 Lock NVRAM access to all NVRAM locations that were written to.
114 At the end display as much info as possible about the configuration
117 =item B<--logfile <logfile>>
119 The logfile to log to. By default logging goes to stdout and stderr.
121 =item B<--keyfile <keyfile>>
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.
127 =item B<--keyfile-fd <file descriptor>>
129 Like B<--keyfile> but the key will be read from the file descriptor.
131 =item B<--pwdfile <passphrase file>>
133 The passphrase file contains a passphrase from which the TPM emulator
134 will derive the encryption key from and use the key for encrypting the TPM
137 =item B<--pwdfile-fd <file descriptor>>
139 Like B<--pwdfile> but the passphrase will be read from the file descriptor.
141 =item B<--ciper <cipher>>
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.
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
153 =item B<--not-overwrite>
155 Do not overwrite existing TPM state. If existing TPM state is found, the
156 program ends without an error.
158 =item B<--vmid <VM ID>>
160 Optional VM ID that can be used to keep track of certificates issued
161 for VMs (or containers). This parameter will be passed through to the tool
162 used for creating the certificates and may be required by that tool.
164 =item B<--pcr-banks <PCR banks>>
166 Optional comma-separated list of PCR banks to activate. Providing '-'
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>
174 =item B<--swtpm_ioctl <executable>>
176 Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl
179 =item B<--tcsd-system-ps-file <file>>
181 This option is deprecated and has no effect (since v0.4).
183 =item B<--rsa-keysize <keysize>> (since v0.4)
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
188 both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key
191 =item B<--reconfigure> (since v0.7)
193 This option allows the reconfiguration of the active PCR banks of a
194 TPM 2 using the I<--pcr-banks> option.
196 =item B<--print-capabilities> (since v0.2)
198 Print capabilities that were added to swtpm_setup after version 0.1.
199 The output may contain the following:
202 "type": "swtpm_setup",
206 "cmdarg-write-ek-cert-files",
207 "cmdarg-create-config-files",
208 "cmdarg-reconfigure-pcr-banks",
209 "tpm2-rsa-keysize-2048",
210 "tpm2-rsa-keysize-3072",
211 "tpm12-not-need-root",
218 The version field is available since v0.7.
220 The meaning of the feature verbs is as follows:
224 =item B<cmdarg-key-fd> (since v0.2)
226 The I<--keyfile-fd> option is supported.
228 =item B<cmdarg-pwd-fd> (since v0.2)
230 The I<--pwdfile-fd> option is supported.
232 =item B<cmdarg-write-ek-cert-files> (since v0.7)
234 The I<--write-ek-cert-files> option is supported.
236 =item B<cmdarg-create-config-files> (since v0.7)
238 The I<--create-config-files> option is supported.
240 =item B<cmdarg-reconfigure-pcr-banks> (since v0.7)
242 The I<--reconfigure> option is supported and allows the reconfiguration of
243 the active PCR banks.
245 =item B<tpm2-rsa-keysize-2048, ...> (since v0.4)
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.
250 =item B<tpm12-not-need-root> (since v0.4)
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,
256 =item B<tpm-1.2> (since v0.7)
258 TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support).
260 =item B<tpm-2.0> (since v0.7)
262 TPM 2 setup is supported (libtpms is compiled with TPM 2 support).
266 =item B<--write-ek-cert-files <directory>> (since v0.7)
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.
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.
278 =item B<--create-config-files [[overwrite][,root][,skip-if-exist]]> (since v0.7)
280 This option allows a user to create configuration files for swtpm_setup and
281 swtpm-localca under the $XDG_CONFIG_HOME or $HOME/.config directories.
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.
287 The meaning of the options is as follows:
293 Overwrite any existing configuration files.
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.
301 =item B<skip-if-exist>
303 Do nothing if any one of the configuration files that would be created already
304 exists. The program will exit without error code.
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.
316 Display the help screen
322 To simulate manufacturing of a TPM, one would typically run the following command:
324 #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
325 --create-ek-cert --create-platform-cert --lock-nvram
327 Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
329 Any user can also simulate the manufacturing of a TPM using the
330 swtpm_localca utility. The following example assumes that the user has
331 set the environment variable XDG_CONFIG_HOME as follows (using bash for
334 export XDG_CONFIG_HOME=~/.config
336 Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
339 The following configuration files need to be created:
341 ~/.config/swtpm_setup.conf:
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
348 ~/.config/swtpm-localca.conf:
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
355 ~/.config/swtpm-localca.options:
357 --platform-manufacturer Fedora
358 --platform-version 2.12
359 --platform-model QEMU
361 Note: The tool swtpm-create-user-config-files can be used to create such
362 files (with different content):
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.
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.
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
382 =head1 REPORTING BUGS
384 Report bugs to Stefan Berger <stefanb@linux.ibm.com>