swtpm_setup(8)

📦
version 0.10.2 · 19 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

okay bestie, this is swtpm_setup(8) — the manual page for swtpm_setup, aka the Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0 💅✨

✨ SYNOPSIS ✨

swtpm_setup [OPTIONS]

💖 DESCRIPTION 💖

okay so swtpm_setup is a tool that prepares the initial state for a libtpms-based TPM. iconic behavior, honestly 🫶

The following options are supported — yes, all of them, bestie, every single flag 👑:

  • --runas <userid> — Use this userid to run swtpm_setup as. Only root can use this option.
  • --config <file> — Path to configuration file containing the tool to use for creating certificates; see also swtpm_setup.conf.

If this parameter is not provided, the default configuration file will be used. The search order for the default configuration file is as follows: if the environment variable XDG_CONFIG_HOME is set, ${XDG_CONFIG_HOME}/swtpm_setup.conf will be used if available; otherwise if the environment variable HOME is set, ${HOME}/.config/swtpm_setup.conf will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf will be used. 🌈

  • --tpm-state <dir> or --tpmstate <dir> — Path where the TPM's state will be written to; this is a mandatory argument. Prefix with dir:// to use directory backend, or file:// to use linear file.
  • --tpm <path to executable> — Path to the TPM executable; this is an optional argument and by default the swtpm executable found in the PATH will be used.
  • --tpm2 — Do setup on a TPM 2; by default a TPM 1.2 is setup.
  • --createek — Create an endorsement key (EK).
  • --allow-signing — Create an EK that can sign. This option requires --tpm2.
This option will create a non-standard EK. When re-creating the EK, TPM 2 tools have to use the EK Template that is written at an NV index corresponding to the created EK (e.g., NV index 0x01c00004 for RS 2048 EK). Otherwise the tool-created EK will not correspond to the actual key being used or the modulus shown in the EK certificate. 😭
Note that the TCG specification "EK Credential Profile For TPM Family 2.0; Level 0" suggests in its section on "EK Usage" that "the Endorsement Key can be a created as a decryption or signing key." However, some platforms will not accept an EK as a signing key, or as a signing and encryption key, and therefore this option should be used very carefully. 💀
  • --decryption — Create an EK that can be used for key encipherment. This is the default unless --allow-signing is passed. This option requires --tpm2.
  • --ecc — Create elliptic curve crypto (ECC) keys; by default RSA keys are generated.
  • --take-ownership — Take ownership; this option implies --createek. This option is only available for TPM 1.2.
  • --ownerpass <password> — Provide custom owner password; default is 'ooo'. This option is only available for TPM 1.2.
  • --owner-well-known — Use a password of all zeros (20 bytes of zeros) as the owner password. This option is only available for TPM 1.2.
  • --srkpass <password> — Provide custom SRK password; default is 'sss'. This option is only available for TPM 1.2.
  • --srk-well-known — Use a password of all zeros (20 bytes of zeros) as the SRK password. This option is only available for TPM 1.2.
  • --create-ek-cert — Create an EK certificate; this implies --createek.
  • --create-platform-cert — Create a platform certificate; this implies --create-ek-cert.
  • --lock-nvram — Lock NVRAM access to all NVRAM locations that were written to.
  • --display — At the end display as much info as possible about the configuration of the TPM.
  • --logfile <logfile> — The logfile to log to. By default logging goes to stdout and stderr.
  • --keyfile <keyfile> — The key file contains an ASCII hex key consisting of 32 hex digits with an optional leading '0x'. This is the key to be used by the TPM emulator for encrypting the state of the TPM.
  • --keyfile-fd <file descriptor> — Like --keyfile but the key will be read from the file descriptor.
  • --pwdfile <passphrase file> — The passphrase file contains a passphrase from which the TPM emulator will derive the encryption key from and use the key for encrypting the TPM state.
  • --pwdfile-fd <file descriptor> — Like --pwdfile but the passphrase will be read from the file descriptor.
  • --ciper <cipher> — The cipher may be either aes-cbc or aes-128-cbc for 128 bit AES encryption, or aes-256-cbc for 256 bit AES encryption. The same cipher must be used on the swtpm command line later on. (yes, it's spelled ciper here — we keep it exactly as the page says 💅)
  • --overwrite — Overwrite existing TPM state. All previous state will be erased. If this option is not given and an existing state file is found, an error code is returned. 😭
  • --not-overwrite — Do not overwrite existing TPM state. If existing TPM state is found, the program ends without an error.
  • --vmid <VM ID> — Optional VM ID that can be used to keep track of certificates issued for VMs (or containers). This parameter will be passed through to the tool used for creating the certificates and may be required by that tool.
  • --pcr-banks <PCR banks> — Optional comma-separated list of PCR banks to activate. Providing '-' allows a user to skip the selection and activates all PCR banks. If this option is not provided, the swtpm_setup.conf configuration file will be consulted for the active_pcr_banks entry. If no such entry is found then the default set of PCR banks will be activated. The default set of PCR banks can be determined using the --help option.
  • --swtpm_ioctl <executable> — Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl in the PATH is used.
  • --tcsd-system-ps-file <file> — This option is deprecated and has no effect (since v0.4). 🙈
  • --rsa-keysize <keysize> (since v0.4) — This option allows to pass the size of a TPM 2 RSA EK key, such as 2048 or 3072. The supported keysizes for a TPM 2 can be queried for using the --print-capabilities option. The default size is 2048 bits for both TPM 1.2 and TPM 2. If 'max' is passed, the largest possible key size is used.
  • --reconfigure (since v0.7) — This option allows the reconfiguration of the active PCR banks of a TPM 2 using the --pcr-banks option.
  • --profile <json-profile> (since v0.10) — Configure a TPM 2 with the given profile. Example profiles look like this:
               {"Name": "null"}

               {"Name": "default-v1"}

               {
                "Name": "custom",
                "Algorithms":"rsa,rsa-min-size=1024,tdes-min-size=128,hmac,aes,\
                              aes-min-size=128,mgf1,keyedhash,xor,sha256,sha384,\
                              sha512,null,rsassa,rsaes,rsapss,oaep,ecdsa,ecdh,ecdaa,\
                              sm2,ecschnorr,ecmqv,kdf1-sp800-56a,kdf2,kdf1-sp800-108,\
                              ecc,ecc-min-size=192,ecc-nist,ecc-bn,symcipher,camellia,\
                              camellia-min-size=128,cmac,ctr,ofb,cbc,cfb,ecb"
               }

The JSON profile must contain the 'name' field with a name of a profile supported by libtpms. Only the 'custom' profile, or profiles whose name starts with 'custom:', are modifiable and may contain Algorithms, Commands, or Attributes fields with user selections. Unknown fields in the JSON profile will be ignored. For further information see the swtpm man page.

  • --profile-name <profile filename| built-in profile name (since v0.10) — Configure a TPM 2 with a profile loaded from either one of the following locations in the shown order, unless qualified by a prefix:
    • local profiles dir specified in swtpm_setup.conf as 'local_profiles_dir'; to force loading the profile from this directory, prefix the name with 'local:'
    • distro profile dir, which is typically /usr/share/swtpm/profiles; to force loading the profile from this directory prefix the name with 'distro:'
    • instantiate a libtpms built-in profile; to force a built-in profile prefix the name with 'builtin:'

All profiles loaded from the above mentioned directories require that the file is available under the given name with '.json' appended.

Use the --print-profiles and --tpm2 options to display all available profiles.

  • --profile-file <file> (since v0.10) — Configure a TPM 2 with a profile from a file.
  • --profile-file-fd <fd> (since v0.10) — Configure a TPM 2 with a profile read from a file descriptor.
  • --profile-remove-disabled check|fips-host (since v0.10) — When this option is passed then swtpm will remove algorithms from the given profile that OpenSSL cannot use when FIPS mode is enabled on the host. If the check parameter is given then algorithms are tested before they are removed while the fips-host parameter forces the removal of all potentially disabled algorithms without testing them.

This option only works if the 'custom' profile is referenced by passing --profile '{"Name":"custom:test"}' for example.

This option passes the remove-disable option parameter as part of the --profile option to swtpm. For further information see the man page for swtpm.

  • --print-profiles (since v0.10) — Print all profiles found in the local and disto profiles directories and display the built-in ones. All profiles stored in files must have the .json extension. The names in the displayed JSON will show the name under which these profiles can be loaded with the --profile-name option, i.e., they will show their filename without the .json extension. Therefore, a profile with filename myprofile.json will show the Name 'myprofile'. The author of the profile may want to set the Name in the profile's JSON to 'custom:myprofile'.
  • --print-capabilities (since v0.2) — Print capabilities that were added to swtpm_setup after version 0.1. The output may contain the following:
               {
                 "type": "swtpm_setup",
                 "features": [
                   "tpm-1.2",
                   "tpm-2.0",
                   "cmdarg-keyfile-fd",
                   "cmdarg-pwdfile-fd",
                   "tpm12-not-need-root",
                   "cmdarg-write-ek-cert-files",
                   "cmdarg-create-config-files",
                   "cmdarg-reconfigure-pcr-banks",
                   "tpm2-rsa-keysize-2048",
                   "tpm2-rsa-keysize-3072",
                   "cmdarg-profile",
                   "cmdarg-profile-remove-disabled"
                 ],
                 "version": "0.7.0"
               }

The version field is available since v0.7. 💜

  • cmdarg-key-fd (since v0.2) — means the --keyfile-fd option is supported. ✨
  • cmdarg-pwd-fd (since v0.2) — means the --pwdfile-fd option is supported. ✨
  • cmdarg-write-ek-cert-files (since v0.7) — means the --write-ek-cert-files option is supported. ✨
  • cmdarg-create-config-files (since v0.7) — means the --create-config-files option is supported. ✨
  • cmdarg-reconfigure-pcr-banks (since v0.7) — means the --reconfigure option is supported, and it lets you reconfigure the active PCR banks. 💅
  • tpm2-rsa-keysize-2048, ... (since v0.4) — the RSA key sizes it lists are the ones supported for a TPM 2's EK key. Lowkey important: if none of the tpm2-rsa-keysize verbs show up, then only RSA 2048 bit keys are supported. 🫶
  • tpm12-not-need-root (since v0.4) — this one implies that any user can set up a TPM 1.2. Before this, only root or the tss user could do it — depending on configuration and whether that account even exists. 👑
  • tpm-1.2 (since v0.7) — TPM 1.2 setup is supported (libtpms is compiled with TPM 1.2 support). 🎀
  • tpm-2.0 (since v0.7) — TPM 2 setup is supported (libtpms is compiled with TPM 2 support). 🎀
  • cmdarg-profile (since v0.10) — means the --profile, profile-file, and --profile-file-fd options are supported. 🌸
  • cmdarg-profile-remove-disabled (since v0.10) — means the --profile-remove-disabled option is supported. 🌸

🦋 --write-ek-cert-files <directory> (since v0.7)

Okay bestie, this one makes endorsement key (EK) files get written into the directory you hand it. Those files contain the DER-formatted EKs that were written into the NVRAM locations of the TPM 1.2 or TPM 2. 😌

The EK files follow the filename pattern ek-<key type>.crt. Examples of actual filenames: ek-rsa2048.crt, ek-rsa3072.crt, and ek-secp384r1.crt. 🗂️

Heads up though — the keys written for a TPM 2 may change over time as the default strength of EK keys changes. Which means: when you're hunting for the EKs, look for all files matching that filename pattern above. No assumptions, fr fr. 💅

🌈 --create-config-files [[overwrite][,root][,skip-if-exist]] (since v0.7)

This lets a user create configuration files for swtpm_setup and swtpm-localca under the $XDG_CONFIG_HOME or $HOME/.config directories. ✨

Important vibe check: the config files will not be created if any one of them already exists — and in that case the program reports the first file it finds and exits with an error code. 😭

Here's what the options mean:

  • overwrite — overwrite any existing configuration files. take the wheel, bestie 🚗
  • root — create the configuration files even under the root account. These config files may then shadow any other existing configuration files, like /etc/swtpm-localca.conf for example. 👀
  • skip-if-exist — do nothing if any one of the configuration files that would be created already exists. The program exits without an error code. chill mode activated 🧘
Note: the case where a user is part of the group that's allowed to access the default configuration files' paths is currently not handled. On many systems this happens when a user is part of the tss group. In that case, the recommended move is to replace the swtpm-localca.conf created by this command with a symbolic link to /etc/swtpm-localca.conf. 🔗

💖 --help, -h

Display the help screen. the bare minimum and yet so iconic 💅

🔥 EXAMPLE USAGE 🔥

To simulate manufacturing of a TPM, you'd typically run this command:

#> sudo swtpm_setup --tpmstate /tmp/mytpm1/ \
    --create-ek-cert --create-platform-cert --lock-nvram
Note: since v0.4, TPM 1.2 setup does not require root rights anymore. we love growth 🥹

Any user can also simulate the manufacturing of a TPM using the swtpm_localca utility. The following example assumes the user has set the environment variable XDG_CONFIG_HOME like this (using bash for example):

export XDG_CONFIG_HOME=~/.config
Note: the XDG_CONFIG_HOME variable is part of the XDG Base Directory Specification. 📚

These configuration files need to be created:

~/.config/swtpm_setup.conf:

# Program invoked for creating certificates
create_certs_tool= /usr/share/swtpm/swtpm-localca
create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf
create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options

~/.config/swtpm-localca.conf:

statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca
signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem
issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem
certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial

~/.config/swtpm-localca.options:

--platform-manufacturer Fedora
--platform-version 2.12
--platform-model QEMU
Note: the tool swtpm-create-user-config-files can be used to create such files (with different content, fyi):
#> /usr/share/swtpm/swtpm-create-user-config-files
Writing /home/stefanb/.config/swtpm_setup.conf.
Writing /home/stefanb/.config/swtpm-localca.conf.
Writing /home/stefanb/.config/swtpm-localca.options.

The following commands now create a TPM 2 with an EK and platform certificate. The state of the TPM 2 gets stored in the directory ${XDG_CONFIG_HOME}/mytpm1. 🌟

#> mkdir -p ${XDG_CONFIG_HOME}/mytpm1
#> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \
    --create-ek-cert --create-platform-cert --lock-nvram

🎀 SEE ALSO 🎀

swtpm_setup.conf

🙈 REPORTING BUGS 🙈

Report bugs to Stefan Berger <stefanb@linux.ibm.com> — be nice, they're doing great 💜

okay that's the whole page bestie, go forth and manufacture some TPMs 💅✨ this is from swtpm, dated 2026-08-23, and it's swtpm_setup(8) — slay 🦋

📦 where this page comes from