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.sh 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}/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 --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 --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 --tpm2
43 Do setup on a TPM 2; by default a TPM 1.2 is setup.
44 --createek
46 Create an endorsement key (EK).
47 --allow-signing
49 Create an EK that can sign. This option requires --tpm2.
50 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 --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 --ecc
64 Create elliptic curve crypto (ECC) keys; by default RSA keys are
65 generated.
66 --take-ownership
68 Take ownership; this option implies --createek. This option is only
69 available for TPM 1.2.
70 --ownerpass <password>
72 Provide custom owner password; default is 'ooo'. This option is
73 only available for TPM 1.2.
74 --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 --srkpass <password>
80 Provide custom SRK password; default is 'sss'. This option is only
81 available for TPM 1.2.
82 --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 --create-ek-cert
88 Create an EK certificate; this implies --createek.
89 --create-platform-cert
91 Create a platform certificate; this implies --create-ek-cert.
92 --lock-nvram
94 Lock NVRAM access to all NVRAM locations that were written to.
95 --display
97 At the end display as much info as possible about the configuration
98 of the TPM.
99 --logfile <logfile>
101 The logfile to log to. By default logging goes to stdout and
102 stderr.
103 --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 --keyfile-fd <file descriptor>
110 Like --keyfile but the key will be read from the file descriptor.
111 --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 --pwdfile-fd <file descriptor>
118 Like --pwdfile but the passphrase will be read from the file
119 descriptor.
120 --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 --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 --not-overwrite
132 Do not overwrite existing TPM state. If existing TPM state is
133 found, the program ends without an error.
134 --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 --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 --swtpm_ioctl <executable>
147 Pass the path to the swtpm_ioctl executable. By default the
148 swtpm_ioctl in the PATH is used.
149 --tcsd-system-ps-file <file>
151 This option is deprecated and has no effect (since v0.4).
152 --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 --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 {
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 The meaning of the feature verbs is as follows:
176 cmdarg-key-fd
178 The --keyfile-fd option is supported.
179 cmdarg-pwd-fd
181 The --pwdfile-fd option is supported.
182 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 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 --help, -h
194 Display the help screen
195
197 To simulate manufacturing of a TPM, one would typically run the
198 following command:
199 #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
201 --create-ek-cert --create-platform-cert --lock-nvram
202 Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
204 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 export XDG_CONFIG_HOME=~/.config
211 Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
213 Specification.
214 The following configuration files need to be created:
216 ~/.config/swtpm_setup.conf:
218 # 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 ~/.config/swtpm-localca.conf:
225 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 ~/.config/swtpm-localca.options:
232 --platform-manufacturer Fedora
234 --platform-version 2.12
235 --platform-model QEMU
236 Note: The tool swtpm-create-user-config-files can be used to create
238 such files (with different content):
239 #> /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 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 #> 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
254 swtpm_setup.conf
255
257 Report bugs to Stefan Berger <stefanb@linux.ibm.com>
258swtpm 2020-12-26 swtpm_setup(8)