swtpm_setup(8)

💖 swtpm_setup — the manual (section 8, bestie) 💖

okay so. bestie. welcome to swtpm_setup(8). this is the glow-up guide for the tool that simulates the manufacturing of a TPM 1.2 or a TPM 2.0. yes really. we're building a fake little factory for a fake little chip and it's iconic. 🏭✨

---

✨ NAME ✨

swtpm_setup — the Swtpm tool that simulates the manufacturing of a TPM 1.2 or 2.0. that's it, that's the whole vibe. 💅

---

🎀 SYNOPSIS 🎀

swtpm_setup [OPTIONS]

like. that's the whole thing. options only. no positional drama. periodt.

---

🦋 DESCRIPTION 🦋

swtpm_setup is a tool that prepares the initial state for a libtpms-based TPM. think of it as the getting-ready-with-me of TPMs — someone has to set the state up before the real work starts, and that someone is this program. 💖

The following options are supported:

• --runas <userid> — run swtpm_setup.sh as this userid. Only 'root' can use this option. everyone else, sit down. 🙈
• --config <file> — path to a configuration file that holds the tool to use for creating certificates; peep swtpm_setup.conf too. If you don't pass this parameter, the default configuration file gets used, and the search order for that default file goes like this:
  1. if the environment variable XDG_CONFIG_HOME is set, then ${XDG_CONFIG_HOME}/swtpm_setup.conf is used if available;
  2. otherwise, if the environment variable HOME is set, then ${HOME}/.config/swtpm_setup.conf is used if available;
  3. if neither of the previous ones is available, /etc/swtpm_setup.conf is used.

yes it's a whole ranked list. slay. 🌸

• --tpm-state <dir> or --tpmstate <dir> — path to the directory where the TPM's state will be written into. this is a mandatory argument, so no skipping it, bestie, it's literally required. 😭
• --tpm <path to executable> — path to the TPM executable. this one's optional, and by default the swtpm executable found in the PATH is used. 🫶
• --tpm2 — do the setup on a TPM 2. by default a TPM 1.2 gets set up. 👑
• --createek — create an endorsement key (EK). 🗝️
• --allow-signing — create an EK that can sign. this option requires --tpm2.

heads up bestie, this one creates 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. so like. respect the template. 🫠

also, 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. like, respectfully, be careful. 💀

• --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. curve appreciation post. 🌈
• --take-ownership — take ownership. this option implies --createek. this option is only available for TPM 1.2. 👑
• --ownerpass <password> — provide a custom owner password; default is 'ooo'. only available for TPM 1.2. 🎀
• --owner-well-known — use a password of all zeros (20 bytes of zeros) as the owner password. only available for TPM 1.2. ⭐
• --srkpass <password> — provide a custom SRK password; default is 'sss'. only available for TPM 1.2. 💜
• --srk-well-known — use a password of all zeros (20 bytes of zeros) as the SRK password. 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. main character behavior, honestly. ✨
• --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. don't switch up mid-relationship. 💅
• --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. this one is destructive, bestie — all previous state, gone, poof. 💀
• --not-overwrite — do not overwrite existing TPM state. if existing TPM state is found, the program ends without an error. the chill option. 😌
• --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. by default the sha1 and sha256 banks are activated. 🏦
• --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). it's giving ghost of options past. 👻
• --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. 📏
• --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": [
        "cmdarg-keyfile-fd",
        "cmdarg-pwdfile-fd",
        "tpm2-rsa-keysize-2048",
        "tpm2-rsa-keysize-3072",
        "tpm12-not-need-root"
      ]
    }

the meaning of the feature verbs is as follows:

• cmdarg-key-fd — the --keyfile-fd option is supported.
• cmdarg-pwd-fd — the --pwdfile-fd option is supported.
• tpm2-rsa-keysize-2048, ... — the shown RSA key sizes are supported for a TPM 2's EK key. if none of the tpm2-rsa-keysize verbs is shown then only RSA 2048 bit keys are supported.
• tpm12-not-need-root (since 0.4.0) — this option implies that any user can setup a TPM 1.2. previously only root or the 'tss' user, depending on configuration and availability of this account, could do that. 🎉

• --help, -h — display the help screen. 🆘

---

🌸 EXAMPLE USAGE 🌸

to simulate manufacturing of a TPM, one would typically run the following 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. 🎉

any user can also simulate the manufacturing of a TPM using the swtpm-localca plugin. the following example assumes that the user has set the environment variable XDG_CONFIG_HOME as follows (using bash for example):

    export XDG_CONFIG_HOME=~/.config

note: the XDG_CONFIG_HOME variable is part of the XDG Base Directory Specification. ✨

the following 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):

  #> /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 will be 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>. he's the one who wants to hear about it, bestie. 🫶

---

and that's the whole page, you ate that. this was swtpm_setup(8) from the swtpm source, dated 2024-07-30. go forth and manufacture ur lil TPM, no cap. 💖✨🎀🦋🌸💅🫶👑🌈⭐🍓🧚💜