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.sh 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}/swtpm_setup.conf will be used if available. If none of the
32           previous ones are available, /etc/swtpm_setup.conf will be used.
33
34       --tpm-state <dir> or --tpmstate <dir>
35           Path to a directory where the TPM's state will be written into;
36           this is a mandatory argument
37
38       --tpm <path to executable>
39           Path to the TPM executable; this is an optional argument and by
40           default the swtpm executable found in the PATH will be used.
41
42       --tpm2
43           Do setup on a TPM 2; by default a TPM 1.2 is setup.
44
45       --createek
46           Create an endorsement key (EK).
47
48       --allow-signing
49           Create an EK that can sign. This option requires --tpm2.
50
51           Note that the TCG specification "EK Credential Profile For TPM
52           Family 2.0; Level 0" suggests in its section on "EK Usage" that
53           "the Endorsement Key can be a created as a decryption or signing
54           key." However, some platforms will not accept an EK as a signing
55           key, or as a signing and encryption key, and therefore this option
56           should be used very carefully.
57
58       --decryption
59           Create an EK that can be used for key encipherment. This is the
60           default unless --allow-signing is passed. This option requires
61           --tpm2.
62
63       --ecc
64           Create elliptic curve crypto (ECC) keys; by default RSA keys are
65           generated.
66
67       --take-ownership
68           Take ownership; this option implies --createek. This option is only
69           available for TPM 1.2.
70
71       --ownerpass  <password>
72           Provide custom owner password; default is 'ooo'. This option is
73           only available for TPM 1.2.
74
75       --owner-well-known
76           Use a password of all zeros (20 bytes of zeros) as the owner
77           password.  This option is only available for TPM 1.2.
78
79       --srkpass <password>
80           Provide custom SRK password; default is 'sss'. This option is only
81           available for TPM 1.2.
82
83       --srk-well-known
84           Use a password of all zeros (20 bytes of zeros) as the SRK
85           password.  This option is only available for TPM 1.2.
86
87       --create-ek-cert
88           Create an EK certificate; this implies --createek.
89
90       --create-platform-cert
91           Create a platform certificate; this implies --create-ek-cert.
92
93       --lock-nvram
94           Lock NVRAM access to all NVRAM locations that were written to.
95
96       --display
97           At the end display as much info as possible about the configuration
98           of the TPM.
99
100       --logfile <logfile>
101           The logfile to log to. By default logging goes to stdout and
102           stderr.
103
104       --keyfile <keyfile>
105           The key file contains an ASCII hex key consisting of 32 hex digits
106           with an optional leading '0x'. This is the key to be used by the
107           TPM emulator for encrypting the state of the TPM.
108
109       --keyfile-fd <file descriptor>
110           Like --keyfile but the key will be read from the file descriptor.
111
112       --pwdfile <passphrase file>
113           The passphrase file contains a passphrase from which the TPM
114           emulator will derive the encyrption key from and use the key for
115           encrypting the TPM state.
116
117       --pwdfile-fd <file descriptor>
118           Like --pwdfile but the passphrase will be read from the file
119           descriptor.
120
121       --ciper <cipher>
122           The cipher may be either aes-cbc or aes-128-cbc for 128 bit AES
123           encryption, or aes-256-cbc for 256 bit AES encryption. The same
124           cipher must be used on the swtpm command line later on.
125
126       --overwrite
127           Overwrite existing TPM state. All previous state will be erased.
128           If this option is not given and an existing state file is found, an
129           error code is returned.
130
131       --not-overwrite
132           Do not overwrite existing TPM state. If existing TPM state is
133           found, the program ends without an error.
134
135       --vmid <VM ID>
136           Optional VM ID that can be used to keep track of certificates
137           issued for VMs (or containers). This parameter will be passed
138           through to the tool used for creating the certificates and may be
139           required by that tool.
140
141       --pcr-banks <PCR banks>
142           Optional comma-separated list of PCR banks to activate. Providing
143           '-' allows a user to skip the selection and activates all PCR
144           banks. By default the sha1 and sha256 banks are activated.
145
146       --swtpm_ioctl <executable>
147           Pass the path to the swtpm_ioctl executable. By default the
148           swtpm_ioctl in the PATH is used.
149
150       --tcsd-system-ps-file <file>
151           This option is deprecated and has no effect (since v0.4).
152
153       --rsa-keysize <keysize> (since v0.4)
154           This option allows to pass the size of a TPM 2 RSA EK key, such as
155           2048 or 3072. The supported keysizes for a TPM 2 can be queried for
156           using the --print-capabilities option. The default size is 2048
157           bits for both TPM 1.2 and TPM 2. If 'max' is passed, the largest
158           possible key size is used.
159
160       --print-capabilities (since v0.2)
161           Print capabilities that were added to swtpm_setup after version
162           0.1.  The output may contain the following:
163
164               {
165                 "type": "swtpm_setup",
166                 "features": [
167                   "cmdarg-keyfile-fd",
168                   "cmdarg-pwdfile-fd",
169                   "tpm2-rsa-keysize-2048",
170                   "tpm2-rsa-keysize-3072",
171                   "tpm12-not-need-root"
172                 ]
173               }
174
175           The meaning of the feature verbs is as follows:
176
177           cmdarg-key-fd
178               The --keyfile-fd option is supported.
179
180           cmdarg-pwd-fd
181               The --pwdfile-fd option is supported.
182
183           tpm2-rsa-keysize-2048, ...
184               The shown RSA key sizes are supported for a TPM 2's EK key. If
185               none of the tpm2-rsa-keysize verbs is shown then only RSA 2048
186               bit keys are supported.
187
188           tpm12-not-need-root (since 0.4.0)
189               This option implies that any user can setup a TPM 1.2.
190               Previously only root or the 'tss' user, depending on
191               configuration and availability of this account, could do that.
192
193       --help, -h
194           Display the help screen
195

EXAMPLE USAGE

197       To simulate manufacturing of a TPM, one would typically run the
198       following command:
199
200         #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
201             --create-ek-cert --create-platform-cert --lock-nvram
202
203       Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
204
205       Any user can also simulate the manufacturing of a TPM using the swtpm-
206       localca plugin. The following example assumes that the user has set the
207       environment variable XDG_CONFIG_HOME as follows (using bash for
208       example):
209
210           export XDG_CONFIG_HOME=~/.config
211
212       Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
213       Specification.
214
215       The following configuration files need to be created:
216
217       ~/.config/swtpm_setup.conf:
218
219           # Program invoked for creating certificates
220           create_certs_tool= /usr/share/swtpm/swtpm-localca
221           create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
222           create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options
223
224       ~/.config/swtpm-localca.conf:
225
226           statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
227           signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
228           issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
229           certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial
230
231       ~/.config/swtpm-localca.options:
232
233           --platform-manufacturer Fedora
234           --platform-version 2.12
235           --platform-model QEMU
236
237       Note: The tool swtpm-create-user-config-files can be used to create
238       such files (with different content):
239
240         #> /usr/share/swtpm/swtpm-create-user-config-files
241         Writing /home/stefanb/.config/swtpm_setup.conf.
242         Writing /home/stefanb/.config/swtpm-localca.conf.
243         Writing /home/stefanb/.config/swtpm-localca.options.
244
245       The following commands now create a TPM 2 with an EK and platform
246       certificate. The state of the TPM 2 will be stored in the directory
247       ${XDG_CONFIG_HOME}/mytpm1.
248
249         #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
250         #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
251             --create-ek-cert --create-platform-cert --lock-nvram
252

SEE ALSO

254       swtpm_setup.conf
255

REPORTING BUGS

257       Report bugs to Stefan Berger <stefanb@linux.ibm.com>
258
259
260
261swtpm                             2021-01-27                    swtpm_setup(8)
Impressum