man/man8/swtpm_setup.pod

   1 =head1 NAME
   2
   3 swtpm_setup - Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0
   4
   5 =head1 SYNOPSIS
   6
   7 B<swtpm_setup [OPTIONS]>
   8
   9 =head1 DESCRIPTION
  10
  11 B<swtpm_setup> is a tool that prepares the initial state for a libtpms-based
  12 TPM.
  13
  14 The following options are supported:
  15
  16 =over 4
  17
  18 =item B<--runas <userid>>
  19
  20 Use this userid to run swtpm_setup as. Only 'root' can use this option.
  21
  22 =item B<--config <file>>
  23
  24 Path to configuration file containing the tool to use for creating
  25 certificates; see also B<swtpm_setup.conf>
  26
  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}/swtpm_setup.conf
  32 will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf
  33 will be used.
  34
  35 =item B<--tpm-state <dir>> or B<--tpmstate <dir>>
  36
  37 Path to a directory where the TPM's state will be written into;
  38 this is a mandatory argument
  39
  40 =item B<--tpm <path to executable>>
  41
  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.
  44
  45 =item B<--tpm2>
  46
  47 Do setup on a TPM 2; by default a TPM 1.2 is setup.
  48
  49 =item B<--createek>
  50
  51 Create an endorsement key (EK).
  52
  53 =item B<--allow-signing>
  54
  55 Create an EK that can sign. This option requires --tpm2.
  56
  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.
  62
  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.
  68
  69 =item B<--decryption>
  70
  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.
  73
  74 =item B<--ecc>
  75
  76 Create elliptic curve crypto (ECC) keys; by default RSA keys are generated.
  77
  78 =item B<--take-ownership>
  79
  80 Take ownership; this option implies --createek. This option is only available for TPM 1.2.
  81
  82 =item B<--ownerpass  <password>>
  83
  84 Provide custom owner password; default is 'ooo'. This option is only available for TPM 1.2.
  85
  86 =item B<--owner-well-known>
  87
  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.
  90
  91 =item B<--srkpass <password>>
  92
  93 Provide custom SRK password; default is 'sss'. This option is only available for TPM 1.2.
  94
  95 =item B<--srk-well-known>
  96
  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.
  99
 100 =item B<--create-ek-cert>
 101
 102 Create an EK certificate; this implies --createek.
 103
 104 =item B<--create-platform-cert>
 105
 106 Create a platform certificate; this implies --create-ek-cert.
 107
 108 =item B<--lock-nvram>
 109
 110 Lock NVRAM access to all NVRAM locations that were written to.
 111
 112 =item B<--display>
 113
 114 At the end display as much info as possible about the configuration
 115 of the TPM.
 116
 117 =item B<--logfile <logfile>>
 118
 119 The logfile to log to. By default logging goes to stdout and stderr.
 120
 121 =item B<--keyfile <keyfile>>
 122
 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.
 126
 127 =item B<--keyfile-fd <file descriptor>>
 128
 129 Like B<--keyfile> but the key will be read from the file descriptor.
 130
 131 =item B<--pwdfile <passphrase file>>
 132
 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
 135 state.
 136
 137 =item B<--pwdfile-fd <file descriptor>>
 138
 139 Like B<--pwdfile> but the passphrase will be read from the file descriptor.
 140
 141 =item B<--ciper <cipher>>
 142
 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.
 146
 147 =item B<--overwrite>
 148
 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
 151 code is returned.
 152
 153 =item B<--not-overwrite>
 154
 155 Do not overwrite existing TPM state. If existing TPM state is found, the
 156 program ends without an error.
 157
 158 =item B<--vmid <VM ID>>
 159
 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.
 163
 164 =item B<--pcr-banks <PCR banks>>
 165
 166 Optional comma-separated list of PCR banks to activate. Providing '-'
 167 allows a user to skip the selection and activates all PCR banks. By default
 168 the sha1 and sha256 banks are activated.
 169
 170 =item B<--swtpm_ioctl <executable>>
 171
 172 Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl
 173 in the PATH is used.
 174
 175 =item B<--tcsd-system-ps-file <file>>
 176
 177 This option is deprecated and has no effect (since v0.4).
 178
 179 =item B<--rsa-keysize <keysize>> (since v0.4)
 180
 181 This option allows to pass the size of a TPM 2 RSA EK key, such as 2048
 182 or 3072. The supported keysizes for a TPM 2 can be queried for using
 183 the I<--print-capabilities> option. The default size is 2048 bits for
 184 both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key
 185 size is used.
 186
 187 =item B<--print-capabilities> (since v0.2)
 188
 189 Print capabilities that were added to swtpm_setup after version 0.1.
 190 The output may contain the following:
 191
 192     {
 193       "type": "swtpm_setup",
 194       "features": [
 195         "cmdarg-keyfile-fd",
 196         "cmdarg-pwdfile-fd",
 197         "cmdarg-write-ek-cert-files",
 198         "tpm2-rsa-keysize-2048",
 199         "tpm2-rsa-keysize-3072",
 200         "tpm12-not-need-root",
 201         "tpm-1.2",
 202         "tpm-2.0"
 203       ],
 204       "version": "0.7.0"
 205     }
 206
 207 The version field is available since 0.7.
 208
 209 The meaning of the feature verbs is as follows:
 210
 211 =over 4
 212
 213 =item B<cmdarg-key-fd>
 214
 215 The I<--keyfile-fd> option is supported.
 216
 217 =item B<cmdarg-pwd-fd>
 218
 219 The I<--pwdfile-fd> option is supported.
 220
 221 =item B<cmdarg-write-ek-cert-files>
 222
 223 The I<--write-ek-cert-files> option is supported
 224
 225 =item B<tpm2-rsa-keysize-2048, ...>
 226
 227 The shown RSA key sizes are supported for a TPM 2's EK key. If none of the
 228 tpm2-rsa-keysize verbs is shown then only RSA 2048 bit keys are supported.
 229
 230 =item B<tpm12-not-need-root> (since 0.4.0)
 231
 232 This option implies that any user can setup a TPM 1.2. Previously only root
 233 or the 'tss' user, depending on configuration and availability of this account,
 234 could do that.
 235
 236 =item B<tpm-1.2> (since 0.7)
 237
 238 TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support).
 239
 240 ==item B<tpm-2.0> (since 0.7)
 241
 242 TPM 2 setup is supported (libtpms is compiled with TPM 2 support).
 243
 244 =back
 245
 246 =item B<--write-ek-cert-files <directory>>
 247
 248 This option causes endorsement key (EK) files to be written into the provided
 249 directory. The files contain the DER-formatted EKs that were written into the
 250 NVRAM locations of the TPM 1.2 or TPM 2. The EK files have the filename pattern
 251 of ek-<key type>.crt. Example for filenames are ek-rsa2048.crt, ek-rsa3072.crt,
 252 and ek-secp384r1.crt.
 253
 254 The keys that are written for a TPM 2 may change over time as the default
 255 strength of the EK keys changes. This means that one should look for all
 256 files with the above filename pattern when looking for the EKs.
 257
 258 =item B<--help, -h>
 259
 260 Display the help screen
 261
 262 =back
 263
 264 =head1 EXAMPLE USAGE
 265
 266 To simulate manufacturing of a TPM, one would typically run the following command:
 267
 268   #> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
 269       --create-ek-cert --create-platform-cert --lock-nvram
 270
 271 Note: since v0.4 TPM 1.2 setup does not require root rights anymore.
 272
 273 Any user can also simulate the manufacturing of a TPM using the
 274 swtpm_localca utility. The following example assumes that the user has
 275 set the environment variable XDG_CONFIG_HOME as follows (using bash for
 276 example):
 277
 278     export XDG_CONFIG_HOME=~/.config
 279
 280 Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory
 281 Specification.
 282
 283 The following configuration files need to be created:
 284
 285 ~/.config/swtpm_setup.conf:
 286
 287     # Program invoked for creating certificates
 288     create_certs_tool= /usr/share/swtpm/swtpm-localca
 289     create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
 290     create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options
 291
 292 ~/.config/swtpm-localca.conf:
 293
 294     statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
 295     signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
 296     issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
 297     certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial
 298
 299 ~/.config/swtpm-localca.options:
 300
 301     --platform-manufacturer Fedora
 302     --platform-version 2.12
 303     --platform-model QEMU
 304
 305 Note: The tool swtpm-create-user-config-files can be used to create such
 306 files (with different content):
 307
 308   #> /usr/share/swtpm/swtpm-create-user-config-files
 309   Writing /home/stefanb/.config/swtpm_setup.conf.
 310   Writing /home/stefanb/.config/swtpm-localca.conf.
 311   Writing /home/stefanb/.config/swtpm-localca.options.
 312
 313 The following commands now create a TPM 2 with an EK and platform
 314 certificate. The state of the TPM 2 will be stored in the directory
 315 ${XDG_CONFIG_HOME}/mytpm1.
 316
 317   #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
 318   #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
 319       --create-ek-cert --create-platform-cert --lock-nvram
 320
 321
 322 =head1 SEE ALSO
 323
 324 B<swtpm_setup.conf>
 325
 326 =head1 REPORTING BUGS
 327
 328 Report bugs to Stefan Berger <stefanb@linux.ibm.com>