1swtpm_setup(8) swtpm_setup(8)
2
6 swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or
7 2.0
8
10 swtpm_setup [OPTIONS]
11
13 swtpm_setup is a tool that prepares the initial state for a libtpms-
14 based TPM.
15 The following options are supported:
17 --runas <userid>
19 Use this userid to run swtpm_setup as. Only 'root' can use this
20 option.
21 --config <file>
23 Path to configuration file containing the tool to use for creating
24 certificates; see also swtpm_setup.conf
25 If this parameter is not provided, the default configuration file
27 will be used. The search order for the default configuration file
28 is as follows. If the environment variable XDG_CONFIG_HOME is set,
29 ${XDG_CONFIG_HOME}/swtpm_setup.conf will be used if available,
30 otherwise if the environment variable HOME is set,
31 ${HOME}/.config/swtpm_setup.conf will be used if available. If none
32 of the previous ones are available, /etc/swtpm_setup.conf will be
33 used.
34 --tpm-state <dir> or --tpmstate <dir>
36 Path where the TPM's state will be written to; this is a mandatory
37 argument. Prefix with dir:// to use directory backend, or file://
38 to use linear file.
39 --tpm <path to executable>
41 Path to the TPM executable; this is an optional argument and by
42 default the swtpm executable found in the PATH will be used.
43 --tpm2
45 Do setup on a TPM 2; by default a TPM 1.2 is setup.
46 --createek
48 Create an endorsement key (EK).
49 --allow-signing
51 Create an EK that can sign. This option requires --tpm2.
52 This option will create a non-standard EK. When re-creating the EK,
54 TPM 2 tools have to use the EK Template that is witten at an NV
55 index corresponding to the created EK (e.g., NV index 0x01c00004
56 for RS 2048 EK). Otherwise the tool-created EK will not correspond
57 to the actual key being used or the modulus shown in the EK
58 certificate.
59 Note that the TCG specification "EK Credential Profile For TPM
61 Family 2.0; Level 0" suggests in its section on "EK Usage" that
62 "the Endorsement Key can be a created as a decryption or signing
63 key." However, some platforms will not accept an EK as a signing
64 key, or as a signing and encryption key, and therefore this option
65 should be used very carefully.
66 --decryption
68 Create an EK that can be used for key encipherment. This is the
69 default unless --allow-signing is passed. This option requires
70 --tpm2.
71 --ecc
73 Create elliptic curve crypto (ECC) keys; by default RSA keys are
74 generated.
75 --take-ownership
77 Take ownership; this option implies --createek. This option is only
78 available for TPM 1.2.
79 --ownerpass <password>
81 Provide custom owner password; default is 'ooo'. This option is
82 only available for TPM 1.2.
83 --owner-well-known
85 Use a password of all zeros (20 bytes of zeros) as the owner
86 password. This option is only available for TPM 1.2.
87 --srkpass <password>
89 Provide custom SRK password; default is 'sss'. This option is only
90 available for TPM 1.2.
91 --srk-well-known
93 Use a password of all zeros (20 bytes of zeros) as the SRK
94 password. This option is only available for TPM 1.2.
95 --create-ek-cert
97 Create an EK certificate; this implies --createek.
98 --create-platform-cert
100 Create a platform certificate; this implies --create-ek-cert.
101 --lock-nvram
103 Lock NVRAM access to all NVRAM locations that were written to.
104 --display
106 At the end display as much info as possible about the configuration
107 of the TPM.
108 --logfile <logfile>
110 The logfile to log to. By default logging goes to stdout and
111 stderr.
112 --keyfile <keyfile>
114 The key file contains an ASCII hex key consisting of 32 hex digits
115 with an optional leading '0x'. This is the key to be used by the
116 TPM emulator for encrypting the state of the TPM.
117 --keyfile-fd <file descriptor>
119 Like --keyfile but the key will be read from the file descriptor.
120 --pwdfile <passphrase file>
122 The passphrase file contains a passphrase from which the TPM
123 emulator will derive the encryption key from and use the key for
124 encrypting the TPM state.
125 --pwdfile-fd <file descriptor>
127 Like --pwdfile but the passphrase will be read from the file
128 descriptor.
129 --ciper <cipher>
131 The cipher may be either aes-cbc or aes-128-cbc for 128 bit AES
132 encryption, or aes-256-cbc for 256 bit AES encryption. The same
133 cipher must be used on the swtpm command line later on.
134 --overwrite
136 Overwrite existing TPM state. All previous state will be erased.
137 If this option is not given and an existing state file is found, an
138 error code is returned.
139 --not-overwrite
141 Do not overwrite existing TPM state. If existing TPM state is
142 found, the program ends without an error.
143 --vmid <VM ID>
145 Optional VM ID that can be used to keep track of certificates
146 issued for VMs (or containers). This parameter will be passed
147 through to the tool used for creating the certificates and may be
148 required by that tool.
149 --pcr-banks <PCR banks>
151 Optional comma-separated list of PCR banks to activate. Providing
152 '-' allows a user to skip the selection and activates all PCR
153 banks. If this option is not provided, the swtpm_setup.conf
154 configuration file will be consulted for the active_pcr_banks
155 entry. If no such entry is found then the default set of PCR banks
156 will be activated. The default set of PCR banks can be determined
157 using the --help option.
158 --swtpm_ioctl <executable>
160 Pass the path to the swtpm_ioctl executable. By default the
161 swtpm_ioctl in the PATH is used.
162 --tcsd-system-ps-file <file>
164 This option is deprecated and has no effect (since v0.4).
165 --rsa-keysize <keysize> (since v0.4)
167 This option allows to pass the size of a TPM 2 RSA EK key, such as
168 2048 or 3072. The supported keysizes for a TPM 2 can be queried for
169 using the --print-capabilities option. The default size is 2048
170 bits for both TPM 1.2 and TPM 2. If 'max' is passed, the largest
171 possible key size is used.
172 --reconfigure (since v0.7)
174 This option allows the reconfiguration of the active PCR banks of a
175 TPM 2 using the --pcr-banks option.
176 --print-capabilities (since v0.2)
178 Print capabilities that were added to swtpm_setup after version
179 0.1. The output may contain the following:
180 {
182 "type": "swtpm_setup",
183 "features": [
184 "cmdarg-keyfile-fd",
185 "cmdarg-pwdfile-fd",
186 "cmdarg-write-ek-cert-files",
187 "cmdarg-create-config-files",
188 "cmdarg-reconfigure-pcr-banks",
189 "tpm2-rsa-keysize-2048",
190 "tpm2-rsa-keysize-3072",
191 "tpm12-not-need-root",
192 "tpm-1.2",
193 "tpm-2.0"
194 ],
195 "version": "0.7.0"
196 }
197 The version field is available since v0.7.
199 The meaning of the feature verbs is as follows:
201 cmdarg-key-fd (since v0.2)
203 The --keyfile-fd option is supported.
204 cmdarg-pwd-fd (since v0.2)
206 The --pwdfile-fd option is supported.
207 cmdarg-write-ek-cert-files (since v0.7)
209 The --write-ek-cert-files option is supported.
210 cmdarg-create-config-files (since v0.7)
212 The --create-config-files option is supported.
213 cmdarg-reconfigure-pcr-banks (since v0.7)
215 The --reconfigure option is supported and allows the
216 reconfiguration of the active PCR banks.
217 tpm2-rsa-keysize-2048, ... (since v0.4)
219 The shown RSA key sizes are supported for a TPM 2's EK key. If
220 none of the tpm2-rsa-keysize verbs is shown then only RSA 2048
221 bit keys are supported.
222 tpm12-not-need-root (since v0.4)
224 This option implies that any user can setup a TPM 1.2.
225 Previously only root or the 'tss' user, depending on
226 configuration and availability of this account, could do that.
227 tpm-1.2 (since v0.7)
229 TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2
230 support).
231 tpm-2.0 (since v0.7)
233 TPM 2 setup is supported (libtpms is compiled with TPM 2
234 support).
235 --write-ek-cert-files <directory> (since v0.7)
237 This option causes endorsement key (EK) files to be written into
238 the provided directory. The files contain the DER-formatted EKs
239 that were written into the NVRAM locations of the TPM 1.2 or TPM 2.
240 The EK files have the filename pattern of ek-<key type>.crt.
241 Example for filenames are ek-rsa2048.crt, ek-rsa3072.crt, and
242 ek-secp384r1.crt.
243 The keys that are written for a TPM 2 may change over time as the
245 default strength of the EK keys changes. This means that one should
246 look for all files with the above filename pattern when looking for
247 the EKs.
248 --create-config-files [[overwrite][,root][,skip-if-exist]] (since v0.7)
250 This option allows a user to create configuration files for
251 swtpm_setup and swtpm-localca under the $XDG_CONFIG_HOME or
252 $HOME/.config directories.
253 The configuration files will not be created if any one of them
255 already exists and in this case the program will report the first
256 file it finds and exit with an error code.
257 The meaning of the options is as follows:
259 overwrite
261 Overwrite any existing configuration files.
262 root
264 Create the configuration files even under the root account.
265 These configuration files may then shadow any other existing
266 configuration files, such as /etc/swtpm-localca.conf for
267 example.
268 skip-if-exist
270 Do nothing if any one of the configuration files that would be
271 created already exists. The program will exit without error
272 code.
273 Note: The case when a user is part of the group that is allowed to
275 access the default configuration files' paths is currently not
276 handled. On many systems this may be the case when a user is part
277 of the 'tss' group. In this case it is recommended that the user
278 replace the swtpm-localca.conf created with this command with a
279 symbolic link to /etc/swtpm-localca.conf.
280 --help, -h
282 Display the help screen
283
285 To simulate manufacturing of a TPM, one would typically run the
286 following command:
287 #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
289 --create-ek-cert --create-platform-cert --lock-nvram
290 Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
292 Any user can also simulate the manufacturing of a TPM using the
294 swtpm_localca utility. The following example assumes that the user has
295 set the environment variable XDG_CONFIG_HOME as follows (using bash for
296 example):
297 export XDG_CONFIG_HOME=~/.config
299 Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
301 Specification.
302 The following configuration files need to be created:
304 ~/.config/swtpm_setup.conf:
306 # Program invoked for creating certificates
308 create_certs_tool= /usr/share/swtpm/swtpm-localca
309 create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
310 create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options
311 ~/.config/swtpm-localca.conf:
313 statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
315 signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
316 issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
317 certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial
318 ~/.config/swtpm-localca.options:
320 --platform-manufacturer Fedora
322 --platform-version 2.12
323 --platform-model QEMU
324 Note: The tool swtpm-create-user-config-files can be used to create
326 such files (with different content):
327 #> /usr/share/swtpm/swtpm-create-user-config-files
329 Writing /home/stefanb/.config/swtpm_setup.conf.
330 Writing /home/stefanb/.config/swtpm-localca.conf.
331 Writing /home/stefanb/.config/swtpm-localca.options.
332 The following commands now create a TPM 2 with an EK and platform
334 certificate. The state of the TPM 2 will be stored in the directory
335 ${XDG_CONFIG_HOME}/mytpm1.
336 #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
338 #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
339 --create-ek-cert --create-platform-cert --lock-nvram
340
342 swtpm_setup.conf
343
345 Report bugs to Stefan Berger <stefanb@linux.ibm.com>
346swtpm 2023-08-16 swtpm_setup(8)