swtpm/man/man8/swtpm_cuse.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_cuse 8"
.TH swtpm_cuse 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 \- TPM Emulator for TPM 1.2 and 2.0 with a CUSE interface only
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBswtpm_cuse [\s-1OPTIONS\s0]\fR
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBswtpm_cuse\fR implements a \s-1TPM\s0 software emulator built on libtpms.
It provides access to \s-1TPM\s0 functionality over a Linux \s-1CUSE\s0
(character device in user space) interface.
.PP
The \fBswtpm_ioctl\fR command should be used for a graceful shutdown
of the \s-1CUSE TPM.\s0
.PP
The following options are supported:
.IP "\fB\-h | \-\-help\fR" 4
.IX Item "-h | --help"
Display help screen.
.IP "\fB\-\-tpmstate dir=<dir>\fR" 4
.IX Item "--tpmstate dir=<dir>"
This parameter allows to set the directory where the \s-1TPM\s0 will
store its persistent state to. If this parameter is not set,
the environment variable \fI\s-1TPM_PATH\s0\fR can be set instead.
.IP "\fB\-n <device name> | \-\-name=<device name> (mandatory)\fR" 4
.IX Item "-n <device name> | --name=<device name> (mandatory)"
The name of the character device to create. To create /dev/vtpm\-200, the
given device name must be vtpm\-200. The character device will be created
automatically and use unused major and minor numbers unless they
are explicitly requested through options.
.IP "\fB\-M <major> | \-\-maj=<major>\fR" 4
.IX Item "-M <major> | --maj=<major>"
The device major number to use; can be omitted.
.IP "\fB\-m <minor> | \-\-min=<minor>\fR" 4
.IX Item "-m <minor> | --min=<minor>"
The device minor number to use; can be omitted.
.IP "\fB\-\-tpm2\fR" 4
.IX Item "--tpm2"
Choose \s-1TPM 2\s0 functionality; by default a \s-1TPM 1.2\s0 is chosen.
.IP "\fB\-r <user> | \-\-runas=<user>\fR" 4
.IX Item "-r <user> | --runas=<user>"
The user to switch to and drop privileges.
.IP "\fB\-\-log fd=<fd>|file=<path>[,level=<n>]\fR[,prefix=<prefix>][,truncate]" 4
.IX Item "--log fd=<fd>|file=<path>[,level=<n>][,prefix=<prefix>][,truncate]"
Enable logging to a file given its file descriptor or its path. Use '\-' for path to
suppress the logging.
.Sp
The level parameter allows to choose the level of logging. Starting at log
level 5, libtpms debug logging is activated.
.Sp
All logged lines will be prefixed with prefix. By default no prefix is prepended.
.Sp
If \fItruncate\fR is passed, the log file will be truncated.
.IP "\fB\-\-locality [reject\-locality\-4][,allow\-set\-locality]\fR" 4
.IX Item "--locality [reject-locality-4][,allow-set-locality]"
The \fIreject\-locality\-4\fR parameter will cause \s-1TPM\s0 error messages to be
returned for requests to set the \s-1TPM\s0 into locality 4.
.Sp
The \fIallow-set-locality\fR parameter allows the swtpm to receive
TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux
\&\s-1VTPM\s0 proxy driver access is enabled by file descriptor passing.
This option is implied by the \fI\-\-vtpm\-proxy\fR option and therefore need not
be explicity set if this option is passed. In all other cases care should be
taken as to who can send the TPM/TPM2_SetLocality command.
.IP "\fB\-\-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]]\fR" 4
.IX Item "--key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]"
Enable encryption of the state files of the \s-1TPM.\s0 The keyfile must contain
an \s-1AES\s0 key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are
supported.
.Sp
The key may be in binary format, in which case the file size must be 16 or
32 bytes. If the key is in hex format (default), the key may consist of 32
or 64 hex digits starting with an optional '0x'.
.Sp
The \fImode\fR parameter indicates which block chaining mode is to be used.
Currently aes-cbc (aes\-128\-cbc) and aes\-256\-cbc are supported.
The encrypted data is integrity protected using encrypt-then-mac.
.Sp
The \fIremove\fR parameter will attempt to remove the given keyfile once the key
has been read.
.IP "\fB\-\-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]\fR" 4
.IX Item "--key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]"
This variant of the key parameter allows to provide a passphrase in a file.
The file is read and a key is derived from it using either a \s-1SHA512\s0 hash
or \s-1PBKDF2.\s0 By default \s-1PBKDF2\s0 is used.
.IP "\fB\-\-migration\-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]]\fR" 4
.IX Item "--migration-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]"
The availability of a migration key ensures that the state of the \s-1TPM\s0
will not be revealed in unencrypted form by the swtpm_cuse program when
the \s-1TPM\s0 state blobs are retreived through the ioctl interface.
The migration key is not used for encrypting \s-1TPM\s0 state written to files,
this is what the <I>\-\-key<I> parameter is used for.
.Sp
The migration key and the key used for encrypting the \s-1TPM\s0 state files may be the same.
.Sp
While the key for the \s-1TPM\s0 state files needs to stay with those files it encrypts, the
migration key needs to stay with the \s-1TPM\s0 state blobs. If for example the state of the
\&\s-1TPM\s0 is migrated between hosts in a data center, then the \s-1TPM\s0 migration key must be
available at all the destinations, so in effect it may have to be a key shared across
all machines in the datacenter. In contrast to that, the key used for encrypting the
\&\s-1TPM\s0 state <B>files<B> can be different for each \s-1TPM\s0 and need only be available
on the host where the \s-1TPM\s0 state resides.
.Sp
The migration key enables the encryption of the \s-1TPM\s0 state blobs.
The keyfile must contain an \s-1AES\s0 key of supported size; 128 bit (16 bytes)
and 256 bit (32 bytes) keys are supported.
.Sp
The key may be in binary format, in which case the file size must be 16 or
32 bytes. If the key is in hex format (default), the key may consist of 32
or 64 hex digits starting with an optional '0x'.
.Sp
The \fImode\fR parameter indicates which block chaining mode is to be used.
Currently aes-cbc (aes\-128\-cbc) and aes\-256\-cbc are supported.
The encrypted data is integrity protected using encrypt-then-mac.
.Sp
The \fIremove\fR parameter will attempt to remove the given keyfile once the key
has been read.
.IP "\fB\-\-migration\-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]\fR" 4
.IX Item "--migration-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]"
This variant of the key parameter allows to provide a passphrase in a file.
The file is read and a key is derived from it using either a \s-1SHA512\s0 hash
or \s-1PBKDF2.\s0 By default \s-1PBKDF2\s0 is used.
.IP "\fB\-\-pid file=<pidfile>\fR|fd=<filedescriptor>>" 4
.IX Item "--pid file=<pidfile>|fd=<filedescriptor>>"
This options allows to set the name of file where the process \s-1ID\s0 (pid) of the \s-1CUSE TPM\s0
will be written into. The file will be written by the root user. It is also possible to
pass a file descriptor to a file that has been opened for writing.
.IP "\fB\-\-seccomp action=none|log|kill\fR (since v0.2)" 4
.IX Item "--seccomp action=none|log|kill (since v0.2)"
This option allows to select the action to take by the seccomp profile when
a syscall is executed that is not allowed. The default is \fIkill\fR. To disable
the seccomp profile, choose \fInone\fR. The \fIlog\fR action logs offending syscalls.
The \fIlog\fR action is only available if libseccomp supports logging.
.Sp
This option is only available on Linux and only if swtpm was compiled with
libseccomp support.
.IP "\fB\-\-print\-capabilities\fR (since v0.2)" 4
.IX Item "--print-capabilities (since v0.2)"
Print capabilities that were added to swtpm after version 0.1. The output
may contain the following:
.Sp
.Vb 7
\&    {
\&      "type": "swtpm",
\&      "features": [
\&        "cmdarg\-seccomp",
\&        "cmdarg\-key\-fd"
\&      ]
\&    }
.Ve
.Sp
The meaning of the feature verbs is as follows:
.RS 4
.IP "\fBcmdarg-seccomp\fR" 4
.IX Item "cmdarg-seccomp"
The \fI\-\-seccomp\fR option is supported.
.IP "\fBcmdarg-key-fd\fR" 4
.IX Item "cmdarg-key-fd"
The \fI\-\-key\fR option supports the \fIfd=\fR parameter.
.RE
.RS 4
.RE
.SH "EXAMPLES"
.IX Header "EXAMPLES"
To start the \s-1CUSE TPM\s0 and have it create the character device /dev/foo,
use the following commands:
.Sp
.Vb 1
\& # ensure that previous swtpm_cuse using /dev/foo is gone
\&
\& swtpm_ioctl \-s /dev/foo
\&
\& # Start the swtpm with TPM 2 functionality and make it accessible
\& # through /dev/foo. Have the swtpm_cuse write the TPM\*(Aqs persistent
\& # state into the given directory.
\&
\& export TPM_PATH=/tmp/foo
\& mkdir \-p $TPM_PATH
\&
\& swtpm_cuse \-n foo \-\-tpm2
\&
\& # Send TPM_Init to the TPM; this is absolutely necessary
\&
\& swtpm_ioctl \-i /dev/foo
.Ve
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBswtpm_bios\fR, \fBswtpm_ioctl\fR