1swtpm_setup(8)                                                  swtpm_setup(8)
2
3
4

NAME

6       swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or
7       2.0
8

SYNOPSIS

10       swtpm_setup [OPTIONS]
11

DESCRIPTION

13       swtpm_setup is a tool that prepares the initial state for a libtpms-
14       based TPM.
15
16       The following options are supported:
17
18       --runas <userid>
19           Use this userid to run swtpm_setup as. Only 'root' can use this
20           option.
21
22       --config <file>
23           Path to configuration file containing the tool to use for creating
24           certificates; see also swtpm_setup.conf
25
26           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
35       --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
40       --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
44       --tpm2
45           Do setup on a TPM 2; by default a TPM 1.2 is setup.
46
47       --createek
48           Create an endorsement key (EK).
49
50       --allow-signing
51           Create an EK that can sign. This option requires --tpm2.
52
53           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
60           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
67       --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
72       --ecc
73           Create elliptic curve crypto (ECC) keys; by default RSA keys are
74           generated.
75
76       --take-ownership
77           Take ownership; this option implies --createek. This option is only
78           available for TPM 1.2.
79
80       --ownerpass  <password>
81           Provide custom owner password; default is 'ooo'. This option is
82           only available for TPM 1.2.
83
84       --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
88       --srkpass <password>
89           Provide custom SRK password; default is 'sss'. This option is only
90           available for TPM 1.2.
91
92       --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
96       --create-ek-cert
97           Create an EK certificate; this implies --createek.
98
99       --create-platform-cert
100           Create a platform certificate; this implies --create-ek-cert.
101
102       --lock-nvram
103           Lock NVRAM access to all NVRAM locations that were written to.
104
105       --display
106           At the end display as much info as possible about the configuration
107           of the TPM.
108
109       --logfile <logfile>
110           The logfile to log to. By default logging goes to stdout and
111           stderr.
112
113       --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
118       --keyfile-fd <file descriptor>
119           Like --keyfile but the key will be read from the file descriptor.
120
121       --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
126       --pwdfile-fd <file descriptor>
127           Like --pwdfile but the passphrase will be read from the file
128           descriptor.
129
130       --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
135       --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
140       --not-overwrite
141           Do not overwrite existing TPM state. If existing TPM state is
142           found, the program ends without an error.
143
144       --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
150       --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
159       --swtpm_ioctl <executable>
160           Pass the path to the swtpm_ioctl executable. By default the
161           swtpm_ioctl in the PATH is used.
162
163       --tcsd-system-ps-file <file>
164           This option is deprecated and has no effect (since v0.4).
165
166       --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
173       --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
177       --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
181               {
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
198           The version field is available since v0.7.
199
200           The meaning of the feature verbs is as follows:
201
202           cmdarg-key-fd (since v0.2)
203               The --keyfile-fd option is supported.
204
205           cmdarg-pwd-fd (since v0.2)
206               The --pwdfile-fd option is supported.
207
208           cmdarg-write-ek-cert-files (since v0.7)
209               The --write-ek-cert-files option is supported.
210
211           cmdarg-create-config-files (since v0.7)
212               The --create-config-files option is supported.
213
214           cmdarg-reconfigure-pcr-banks (since v0.7)
215               The --reconfigure option is supported and allows the
216               reconfiguration of the active PCR banks.
217
218           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
223           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
228           tpm-1.2 (since v0.7)
229               TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2
230               support).
231
232           tpm-2.0 (since v0.7)
233               TPM 2 setup is supported (libtpms is compiled with TPM 2
234               support).
235
236       --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
244           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
249       --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
254           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
258           The meaning of the options is as follows:
259
260           overwrite
261               Overwrite any existing configuration files.
262
263           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
269           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
274           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
281       --help, -h
282           Display the help screen
283

EXAMPLE USAGE

285       To simulate manufacturing of a TPM, one would typically run the
286       following command:
287
288         #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
289             --create-ek-cert --create-platform-cert --lock-nvram
290
291       Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
292
293       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
298           export XDG_CONFIG_HOME=~/.config
299
300       Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
301       Specification.
302
303       The following configuration files need to be created:
304
305       ~/.config/swtpm_setup.conf:
306
307           # 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
312       ~/.config/swtpm-localca.conf:
313
314           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
319       ~/.config/swtpm-localca.options:
320
321           --platform-manufacturer Fedora
322           --platform-version 2.12
323           --platform-model QEMU
324
325       Note: The tool swtpm-create-user-config-files can be used to create
326       such files (with different content):
327
328         #> /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
333       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
337         #> 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

SEE ALSO

342       swtpm_setup.conf
343

REPORTING BUGS

345       Report bugs to Stefan Berger <stefanb@linux.ibm.com>
346
347
348
349swtpm                             2023-08-16                    swtpm_setup(8)
Impressum