.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "swtpm_setup 8" .TH swtpm_setup 8 "2022-08-22" "swtpm" "" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" swtpm_setup \- Swtpm tool to simulate the manufacturing of a TPM 1.2 or 2.0 .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBswtpm_setup [\s-1OPTIONS\s0]\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBswtpm_setup\fR is a tool that prepares the initial state for a libtpms-based \&\s-1TPM.\s0 .PP The following options are supported: .IP "\fB\-\-runas " 4 .IX Item "--runas " Use this userid to run swtpm_setup as. Only 'root' can use this option. .IP "\fB\-\-config " 4 .IX Item "--config " Path to configuration file containing the tool to use for creating certificates; see also \fBswtpm_setup.conf\fR .Sp 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 \s-1XDG_CONFIG_HOME\s0 is set, ${\s-1XDG_CONFIG_HOME\s0}/swtpm_setup.conf will be used if available, otherwise if the environment variable \s-1HOME\s0 is set, ${\s-1HOME\s0}/swtpm_setup.conf will be used if available. If none of the previous ones are available, /etc/swtpm_setup.conf will be used. .IP "\fB\-\-tpm\-state or \fB\-\-tpmstate " 4 .IX Item "--tpm-state or --tpmstate " Path where the \s-1TPM\s0's state will be written to; this is a mandatory argument. Prefix with dir:// to use directory backend, or file:// to use linear file. .IP "\fB\-\-tpm " 4 .IX Item "--tpm " Path to the \s-1TPM\s0 executable; this is an optional argument and by default the swtpm executable found in the \s-1PATH\s0 will be used. .IP "\fB\-\-tpm2\fR" 4 .IX Item "--tpm2" Do setup on a \s-1TPM 2\s0; by default a \s-1TPM 1.2\s0 is setup. .IP "\fB\-\-createek\fR" 4 .IX Item "--createek" Create an endorsement key (\s-1EK\s0). .IP "\fB\-\-allow\-signing\fR" 4 .IX Item "--allow-signing" Create an \s-1EK\s0 that can sign. This option requires \-\-tpm2. .Sp This option will create a non-standard \s-1EK.\s0 When re-creating the \s-1EK, TPM 2\s0 tools have to use the \s-1EK\s0 Template that is witten at an \s-1NV\s0 index corresponding to the created \s-1EK\s0 (e.g., \s-1NV\s0 index 0x01c00004 for \s-1RS 2048 EK\s0). Otherwise the tool-created \s-1EK\s0 will not correspond to the actual key being used or the modulus shown in the \s-1EK\s0 certificate. .Sp Note that the \s-1TCG\s0 specification \*(L"\s-1EK\s0 Credential Profile For \s-1TPM\s0 Family 2.0; Level 0\*(R" suggests in its section on \*(L"\s-1EK\s0 Usage\*(R" that \*(L"the Endorsement Key can be a created as a decryption or signing key.\*(R" However, some platforms will not accept an \s-1EK\s0 as a signing key, or as a signing and encryption key, and therefore this option should be used very carefully. .IP "\fB\-\-decryption\fR" 4 .IX Item "--decryption" Create an \s-1EK\s0 that can be used for key encipherment. This is the default unless \-\-allow\-signing is passed. This option requires \-\-tpm2. .IP "\fB\-\-ecc\fR" 4 .IX Item "--ecc" Create elliptic curve crypto (\s-1ECC\s0) keys; by default \s-1RSA\s0 keys are generated. .IP "\fB\-\-take\-ownership\fR" 4 .IX Item "--take-ownership" Take ownership; this option implies \-\-createek. This option is only available for \s-1TPM 1.2.\s0 .IP "\fB\-\-ownerpass " 4 .IX Item "--ownerpass " Provide custom owner password; default is 'ooo'. This option is only available for \s-1TPM 1.2.\s0 .IP "\fB\-\-owner\-well\-known\fR" 4 .IX Item "--owner-well-known" Use a password of all zeros (20 bytes of zeros) as the owner password. This option is only available for \s-1TPM 1.2.\s0 .IP "\fB\-\-srkpass " 4 .IX Item "--srkpass " Provide custom \s-1SRK\s0 password; default is 'sss'. This option is only available for \s-1TPM 1.2.\s0 .IP "\fB\-\-srk\-well\-known\fR" 4 .IX Item "--srk-well-known" Use a password of all zeros (20 bytes of zeros) as the \s-1SRK\s0 password. This option is only available for \s-1TPM 1.2.\s0 .IP "\fB\-\-create\-ek\-cert\fR" 4 .IX Item "--create-ek-cert" Create an \s-1EK\s0 certificate; this implies \-\-createek. .IP "\fB\-\-create\-platform\-cert\fR" 4 .IX Item "--create-platform-cert" Create a platform certificate; this implies \-\-create\-ek\-cert. .IP "\fB\-\-lock\-nvram\fR" 4 .IX Item "--lock-nvram" Lock \s-1NVRAM\s0 access to all \s-1NVRAM\s0 locations that were written to. .IP "\fB\-\-display\fR" 4 .IX Item "--display" At the end display as much info as possible about the configuration of the \s-1TPM.\s0 .IP "\fB\-\-logfile " 4 .IX Item "--logfile " The logfile to log to. By default logging goes to stdout and stderr. .IP "\fB\-\-keyfile " 4 .IX Item "--keyfile " The key file contains an \s-1ASCII\s0 hex key consisting of 32 hex digits with an optional leading '0x'. This is the key to be used by the \s-1TPM\s0 emulator for encrypting the state of the \s-1TPM.\s0 .IP "\fB\-\-keyfile\-fd " 4 .IX Item "--keyfile-fd " Like \fB\-\-keyfile\fR but the key will be read from the file descriptor. .IP "\fB\-\-pwdfile " 4 .IX Item "--pwdfile " The passphrase file contains a passphrase from which the \s-1TPM\s0 emulator will derive the encryption key from and use the key for encrypting the \s-1TPM\s0 state. .IP "\fB\-\-pwdfile\-fd " 4 .IX Item "--pwdfile-fd " Like \fB\-\-pwdfile\fR but the passphrase will be read from the file descriptor. .IP "\fB\-\-ciper " 4 .IX Item "--ciper " The cipher may be either aes-cbc or aes\-128\-cbc for 128 bit \s-1AES\s0 encryption, or aes\-256\-cbc for 256 bit \s-1AES\s0 encryption. The same cipher must be used on the \fIswtpm\fR command line later on. .IP "\fB\-\-overwrite\fR" 4 .IX Item "--overwrite" Overwrite existing \s-1TPM\s0 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. .IP "\fB\-\-not\-overwrite\fR" 4 .IX Item "--not-overwrite" Do not overwrite existing \s-1TPM\s0 state. If existing \s-1TPM\s0 state is found, the program ends without an error. .IP "\fB\-\-vmid <\s-1VM ID\s0\fR>" 4 .IX Item "--vmid " Optional \s-1VM ID\s0 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. .IP "\fB\-\-pcr\-banks <\s-1PCR\s0 banks\fR>" 4 .IX Item "--pcr-banks " Optional comma-separated list of \s-1PCR\s0 banks to activate. Providing '\-' allows a user to skip the selection and activates all \s-1PCR\s0 banks. If this option is not provided, the \fIswtpm_setup.conf\fR configuration file will be consulted for the active_pcr_banks entry. If no such entry is found then the default set of \s-1PCR\s0 banks will be activated. The default set of \s-1PCR\s0 banks can be determined using the \fI\-\-help\fR option. .IP "\fB\-\-swtpm_ioctl " 4 .IX Item "--swtpm_ioctl " Pass the path to the swtpm_ioctl executable. By default the swtpm_ioctl in the \s-1PATH\s0 is used. .IP "\fB\-\-tcsd\-system\-ps\-file " 4 .IX Item "--tcsd-system-ps-file " This option is deprecated and has no effect (since v0.4). .IP "\fB\-\-rsa\-keysize (since v0.4)" 4 .IX Item "--rsa-keysize (since v0.4)" This option allows to pass the size of a \s-1TPM 2 RSA EK\s0 key, such as 2048 or 3072. The supported keysizes for a \s-1TPM 2\s0 can be queried for using the \fI\-\-print\-capabilities\fR option. The default size is 2048 bits for both \s-1TPM 1.2\s0 and \s-1TPM 2.\s0 If 'max' is passed, the largest possible key size is used. .IP "\fB\-\-reconfigure\fR (since v0.7)" 4 .IX Item "--reconfigure (since v0.7)" This option allows the reconfiguration of the active \s-1PCR\s0 banks of a \&\s-1TPM 2\s0 using the \fI\-\-pcr\-banks\fR option. .IP "\fB\-\-print\-capabilities\fR (since v0.2)" 4 .IX Item "--print-capabilities (since v0.2)" Print capabilities that were added to swtpm_setup after version 0.1. The output may contain the following: .Sp .Vb 10 \& { \& "type": "swtpm_setup", \& "features": [ \& "cmdarg\-keyfile\-fd", \& "cmdarg\-pwdfile\-fd", \& "cmdarg\-write\-ek\-cert\-files", \& "cmdarg\-create\-config\-files", \& "cmdarg\-reconfigure\-pcr\-banks", \& "tpm2\-rsa\-keysize\-2048", \& "tpm2\-rsa\-keysize\-3072", \& "tpm12\-not\-need\-root", \& "tpm\-1.2", \& "tpm\-2.0" \& ], \& "version": "0.7.0" \& } .Ve .Sp The version field is available since v0.7. .Sp The meaning of the feature verbs is as follows: .RS 4 .IP "\fBcmdarg-key-fd\fR (since v0.2)" 4 .IX Item "cmdarg-key-fd (since v0.2)" The \fI\-\-keyfile\-fd\fR option is supported. .IP "\fBcmdarg-pwd-fd\fR (since v0.2)" 4 .IX Item "cmdarg-pwd-fd (since v0.2)" The \fI\-\-pwdfile\-fd\fR option is supported. .IP "\fBcmdarg-write-ek-cert-files\fR (since v0.7)" 4 .IX Item "cmdarg-write-ek-cert-files (since v0.7)" The \fI\-\-write\-ek\-cert\-files\fR option is supported. .IP "\fBcmdarg-create-config-files\fR (since v0.7)" 4 .IX Item "cmdarg-create-config-files (since v0.7)" The \fI\-\-create\-config\-files\fR option is supported. .IP "\fBcmdarg-reconfigure-pcr-banks\fR (since v0.7)" 4 .IX Item "cmdarg-reconfigure-pcr-banks (since v0.7)" The \fI\-\-reconfigure\fR option is supported and allows the reconfiguration of the active \s-1PCR\s0 banks. .IP "\fBtpm2\-rsa\-keysize\-2048, ...\fR (since v0.4)" 4 .IX Item "tpm2-rsa-keysize-2048, ... (since v0.4)" The shown \s-1RSA\s0 key sizes are supported for a \s-1TPM 2\s0's \s-1EK\s0 key. If none of the tpm2\-rsa\-keysize verbs is shown then only \s-1RSA 2048\s0 bit keys are supported. .IP "\fBtpm12\-not\-need\-root\fR (since v0.4)" 4 .IX Item "tpm12-not-need-root (since v0.4)" This option implies that any user can setup a \s-1TPM 1.2.\s0 Previously only root or the 'tss' user, depending on configuration and availability of this account, could do that. .IP "\fBtpm\-1.2\fR (since v0.7)" 4 .IX Item "tpm-1.2 (since v0.7)" \&\s-1TPM 1.2\s0 setup is supported (libtpms is compiled with \s-1TPM 1.2\s0 support). .IP "\fBtpm\-2.0\fR (since v0.7)" 4 .IX Item "tpm-2.0 (since v0.7)" \&\s-1TPM 2\s0 setup is supported (libtpms is compiled with \s-1TPM 2\s0 support). .RE .RS 4 .RE .IP "\fB\-\-write\-ek\-cert\-files (since v0.7)" 4 .IX Item "--write-ek-cert-files (since v0.7)" This option causes endorsement key (\s-1EK\s0) files to be written into the provided directory. The files contain the DER-formatted EKs that were written into the \&\s-1NVRAM\s0 locations of the \s-1TPM 1.2\s0 or \s-1TPM 2.\s0 The \s-1EK\s0 files have the filename pattern of ek\-.crt. Example for filenames are ek\-rsa2048.crt, ek\-rsa3072.crt, and ek\-secp384r1.crt. .Sp The keys that are written for a \s-1TPM 2\s0 may change over time as the default strength of the \s-1EK\s0 keys changes. This means that one should look for all files with the above filename pattern when looking for the EKs. .IP "\fB\-\-create\-config\-files [[overwrite][,root][,skip\-if\-exist]]\fR (since v0.7)" 4 .IX Item "--create-config-files [[overwrite][,root][,skip-if-exist]] (since v0.7)" This option allows a user to create configuration files for swtpm_setup and swtpm-localca under the \f(CW$XDG_CONFIG_HOME\fR or \f(CW$HOME\fR/.config directories. .Sp The configuration files will not be created if any one of them already exists and in this case the program will report the first file it finds and exit with an error code. .Sp The meaning of the options is as follows: .RS 4 .IP "\fBoverwrite\fR" 4 .IX Item "overwrite" Overwrite any existing configuration files. .IP "\fBroot\fR" 4 .IX Item "root" Create the configuration files even under the root account. These configuration files may then shadow any other existing configuration files, such as /etc/swtpm\-localca.conf for example. .IP "\fBskip-if-exist\fR" 4 .IX Item "skip-if-exist" Do nothing if any one of the configuration files that would be created already exists. The program will exit without error code. .RE .RS 4 .Sp Note: The case when a user is part of the group that is allowed to access the default configuration files' paths is currently not handled. On many systems this may be the case when a user is part of the 'tss' group. In this case it is recommended that the user replace the swtpm\-localca.conf created with this command with a symbolic link to /etc/swtpm\-localca.conf. .RE .IP "\fB\-\-help, \-h\fR" 4 .IX Item "--help, -h" Display the help screen .SH "EXAMPLE USAGE" .IX Header "EXAMPLE USAGE" To simulate manufacturing of a \s-1TPM,\s0 one would typically run the following command: .PP .Vb 2 \& #> sudo swtpm_setup \-\-tpmstate /tmp/mytpm1/ \e \& \-\-create\-ek\-cert \-\-create\-platform\-cert \-\-lock\-nvram .Ve .PP Note: since v0.4 \s-1TPM 1.2\s0 setup does not require root rights anymore. .PP Any user can also simulate the manufacturing of a \s-1TPM\s0 using the swtpm_localca utility. The following example assumes that the user has set the environment variable \s-1XDG_CONFIG_HOME\s0 as follows (using bash for example): .PP .Vb 1 \& export XDG_CONFIG_HOME=~/.config .Ve .PP Note: The \s-1XDG_CONFIG_HOME\s0 variable is part of the \s-1XDG\s0 Base Directory Specification. .PP The following configuration files need to be created: .PP ~/.config/swtpm_setup.conf: .PP .Vb 4 \& # 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 .Ve .PP ~/.config/swtpm\-localca.conf: .PP .Vb 4 \& 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 .Ve .PP ~/.config/swtpm\-localca.options: .PP .Vb 3 \& \-\-platform\-manufacturer Fedora \& \-\-platform\-version 2.12 \& \-\-platform\-model QEMU .Ve .PP Note: The tool swtpm-create-user-config-files can be used to create such files (with different content): .PP .Vb 4 \& #> /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. .Ve .PP The following commands now create a \s-1TPM 2\s0 with an \s-1EK\s0 and platform certificate. The state of the \s-1TPM 2\s0 will be stored in the directory ${\s-1XDG_CONFIG_HOME\s0}/mytpm1. .PP .Vb 3 \& #> mkdir \-p ${XDG_CONFIG_HOME}/mytpm1 \& #> swtpm_setup \-\-tpm2 \-\-tpmstate ${XDG_CONFIG_HOME}/mytpm1 \e \& \-\-create\-ek\-cert \-\-create\-platform\-cert \-\-lock\-nvram .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBswtpm_setup.conf\fR .SH "REPORTING BUGS" .IX Header "REPORTING BUGS" Report bugs to Stefan Berger