swtpm/man/man8/swtpm_setup.8

.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" 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 "2019-07-09" "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 utility 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 intial state for a libtpms-based
\&\s-1TPM.\s0
.PP
For creating the initial state of a \s-1TPM 1.2,\s0 swtpm_setup must be run either
as root or as the user the that tcsd requires, which is typically tss.
.PP
The following options are supported:
.IP "\fB\-\-runas <userid\fR>" 4
.IX Item "--runas <userid>"
Use this userid to run swtpm_setup.sh; by default 'tss' is used.
.IP "\fB\-\-config <file\fR>" 4
.IX Item "--config <file>"
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
/etc/swtpm_setup.conf will be used. If the environment variable
\&\s-1XDG_CONFIG_HOME\s0 is set, the configuration file is assumed to be
\&\f(CW$XDG_CONFIG_HOME\fR/swtpm_setup.conf.
.IP "\fB\-\-tpm\-state <dir\fR> or \fB\-\-tpmstate <dir\fR>" 4
.IX Item "--tpm-state <dir> or --tpmstate <dir>"
Path to a directory where the \s-1TPM\s0's state will be written into;
this is a mandatory argument
.IP "\fB\-\-tpm <path to executable\fR>" 4
.IX Item "--tpm <path to executable>"
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 the \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
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 carfully.
.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
.IP "\fB\-\-ownerpass  <password\fR>" 4
.IX Item "--ownerpass <password>"
Provide custom owner password; default is ooo
.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
.IP "\fB\-\-srkpass <password\fR>" 4
.IX Item "--srkpass <password>"
Provide custom \s-1SRK\s0 password; default is sss
.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
.IP "\fB\-\-create\-ek\-cert\fR" 4
.IX Item "--create-ek-cert"
Create an \s-1EK\s0 certificate; this implies \-\-createek
(\s-1NOT SUPPORTED YET\s0)
.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
.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 <logfile\fR>" 4
.IX Item "--logfile <logfile>"
The logfile to log to. By default logging goes to stdout and stderr.
.IP "\fB\-\-keyfile <keyfile\fR>" 4
.IX Item "--keyfile <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 <file descriptor\fR>" 4
.IX Item "--keyfile-fd <file descriptor>"
Like \fB\-\-keyfile\fR but the key will be read from the file descriptor.
.IP "\fB\-\-pwdfile <passphrase file\fR>" 4
.IX Item "--pwdfile <passphrase file>"
The passphrase file contains a passphrase from which the \s-1TPM\s0 emulator
will derive the encyrption key from and use the key for encrypting the \s-1TPM\s0
state.
.IP "\fB\-\-pwdfile\-fd <file descriptor\fR>" 4
.IX Item "--pwdfile-fd <file descriptor>"
Like \fB\-\-pwdfile\fR but the passphrase will be read from the file descriptor.
.IP "\fB\-\-ciper <cipher\fR>" 4
.IX Item "--ciper <cipher>"
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 exising \s-1TPM\s0 state is found, the
program ends without an error.
.IP "\fB\-\-vmid <\s-1VM ID\s0\fR>" 4
.IX Item "--vmid <VM ID>"
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 <PCR banks>"
Optional comma-separated list of \s-1PCR\s0 banks to activate. Providing '\-'
allows to skip the selection and activates all \s-1PCR\s0 banks. By default
the sha1 and sha256 banks are activated.
.IP "\fB\-\-swtpm_ioctl <executable\fR>" 4
.IX Item "--swtpm_ioctl <executable>"
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 <file\fR>" 4
.IX Item "--tcsd-system-ps-file <file>"
A file to copy \s-1TCSD\s0's system_ps_file to. The system_ps_file contains the
\&\s-1TPM 1.2 SRK\s0 public key after taking ownership of the \s-1TPM.\s0 The file is
needed by \s-1TCSD\s0 for key related functions.
.Sp
This option is only useful with \s-1TPM 1.2\s0 and in if ownership is taken.
.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
contains the following:
.Sp
.Vb 7
\&    {
\&      "type": "swtpm_setup",
\&      "features": [
\&        "cmdarg\-keyfile\-fd",
\&        "cmdarg\-pwdfile\-fd"
\&      ]
\&    }
.Ve
.Sp
The meaning of the feature verbs is as follows:
.RS 4
.IP "\fBcmdarg-key-fd\fR" 4
.IX Item "cmdarg-key-fd"
The \fI\-\-keyfile\-fd\fR option is supported.
.IP "\fBcmdarg-pwd-fd\fR" 4
.IX Item "cmdarg-pwd-fd"
The \fI\-\-pwdfile\-fd\fR option is supported.
.RE
.RS 4
.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 setting up a \s-1TPM 1.2\s0 relies on the \fItcsd\fR for some of its operations,
\&\fBswtpm_setup\fR has to be run as root so that it can invoke the \fItcsd\fR either as root
or tss user.
.PP
A normal user can also simulate the manufacturing of a \s-1TPM 2\s0 using the
swtpm-localca plugin. 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
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 <stefanb@linux.vnet.ibm.com>