man/man8/swtpm_cuse.8

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "swtpm_cuse 8"
 136 .TH swtpm_cuse 8 "2019-07-09" "swtpm" ""
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 swtpm \- TPM Emulator for TPM 1.2 and 2.0 with a CUSE interface only
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 \&\fBswtpm_cuse [\s-1OPTIONS\s0]\fR
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 \&\fBswtpm_cuse\fR implements a \s-1TPM\s0 software emulator built on libtpms.
 149 It provides access to \s-1TPM\s0 functionality over a Linux \s-1CUSE\s0
 150 (character device in user space) interface.
 151 .PP
 152 The \fBswtpm_ioctl\fR command should be used for a graceful shutdown
 153 of the \s-1CUSE TPM.\s0
 154 .PP
 155 The following options are supported:
 156 .IP "\fB\-h | \-\-help\fR" 4
 157 .IX Item "-h | --help"
 158 Display help screen.
 159 .IP "\fB\-\-tpmstate dir=<dir>\fR" 4
 160 .IX Item "--tpmstate dir=<dir>"
 161 This parameter allows to set the directory where the \s-1TPM\s0 will
 162 store its persistent state to. If this parameter is not set,
 163 the environment variable \fI\s-1TPM_PATH\s0\fR can be set instead.
 164 .IP "\fB\-n <device name> | \-\-name=<device name> (mandatory)\fR" 4
 165 .IX Item "-n <device name> | --name=<device name> (mandatory)"
 166 The name of the character device to create. To create /dev/vtpm\-200, the
 167 given device name must be vtpm\-200. The character device will be created
 168 automatically and use unused major and minor numbers unless they
 169 are explicitly requested through options.
 170 .IP "\fB\-M <major> | \-\-maj=<major>\fR" 4
 171 .IX Item "-M <major> | --maj=<major>"
 172 The device major number to use; can be omitted.
 173 .IP "\fB\-m <minor> | \-\-min=<minor>\fR" 4
 174 .IX Item "-m <minor> | --min=<minor>"
 175 The device minor number to use; can be omitted.
 176 .IP "\fB\-\-tpm2\fR" 4
 177 .IX Item "--tpm2"
 178 Choose \s-1TPM 2\s0 functionality; by default a \s-1TPM 1.2\s0 is chosen.
 179 .IP "\fB\-r <user> | \-\-runas=<user>\fR" 4
 180 .IX Item "-r <user> | --runas=<user>"
 181 The user to switch to and drop privileges.
 182 .IP "\fB\-\-log fd=<fd>|file=<path>[,level=<n>]\fR[,prefix=<prefix>][,truncate]" 4
 183 .IX Item "--log fd=<fd>|file=<path>[,level=<n>][,prefix=<prefix>][,truncate]"
 184 Enable logging to a file given its file descriptor or its path. Use '\-' for path to
 185 suppress the logging.
 186 .Sp
 187 The level parameter allows to choose the level of logging. Starting at log
 188 level 5, libtpms debug logging is activated.
 189 .Sp
 190 All logged lines will be prefixed with prefix. By default no prefix is prepended.
 191 .Sp
 192 If \fItruncate\fR is passed, the log file will be truncated.
 193 .IP "\fB\-\-locality [reject\-locality\-4][,allow\-set\-locality]\fR" 4
 194 .IX Item "--locality [reject-locality-4][,allow-set-locality]"
 195 The \fIreject\-locality\-4\fR parameter will cause \s-1TPM\s0 error messages to be
 196 returned for requests to set the \s-1TPM\s0 into locality 4.
 197 .Sp
 198 The \fIallow-set-locality\fR parameter allows the swtpm to receive
 199 TPM/TPM2_SetLocality commands. This is parameter is useful if the Linux
 200 \&\s-1VTPM\s0 proxy driver access is enabled by file descriptor passing.
 201 This option is implied by the \fI\-\-vtpm\-proxy\fR option and therefore need not
 202 be explicity set if this option is passed. In all other cases care should be
 203 taken as to who can send the TPM/TPM2_SetLocality command.
 204 .IP "\fB\-\-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]]\fR" 4
 205 .IX Item "--key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]"
 206 Enable encryption of the state files of the \s-1TPM.\s0 The keyfile must contain
 207 an \s-1AES\s0 key of supported size; 128 bit (16 bytes) and 256 bit (32 bytes) keys are
 208 supported.
 209 .Sp
 210 The key may be in binary format, in which case the file size must be 16 or
 211 32 bytes. If the key is in hex format (default), the key may consist of 32
 212 or 64 hex digits starting with an optional '0x'.
 213 .Sp
 214 The \fImode\fR parameter indicates which block chaining mode is to be used.
 215 Currently aes-cbc (aes\-128\-cbc) and aes\-256\-cbc are supported.
 216 The encrypted data is integrity protected using encrypt-then-mac.
 217 .Sp
 218 The \fIremove\fR parameter will attempt to remove the given keyfile once the key
 219 has been read.
 220 .IP "\fB\-\-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]\fR" 4
 221 .IX Item "--key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]"
 222 This variant of the key parameter allows to provide a passphrase in a file.
 223 The file is read and a key is derived from it using either a \s-1SHA512\s0 hash
 224 or \s-1PBKDF2.\s0 By default \s-1PBKDF2\s0 is used.
 225 .IP "\fB\-\-migration\-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]]\fR" 4
 226 .IX Item "--migration-key file=<keyfile>|fd=<fd>[,format=<hex|binary>][,mode=aes-cbc|aes-256-cbc][,remove[=true|false]]"
 227 The availability of a migration key ensures that the state of the \s-1TPM\s0
 228 will not be revealed in unencrypted form by the swtpm_cuse program when
 229 the \s-1TPM\s0 state blobs are retreived through the ioctl interface.
 230 The migration key is not used for encrypting \s-1TPM\s0 state written to files,
 231 this is what the <I>\-\-key<I> parameter is used for.
 232 .Sp
 233 The migration key and the key used for encrypting the \s-1TPM\s0 state files may be the same.
 234 .Sp
 235 While the key for the \s-1TPM\s0 state files needs to stay with those files it encrypts, the
 236 migration key needs to stay with the \s-1TPM\s0 state blobs. If for example the state of the
 237 \&\s-1TPM\s0 is migrated between hosts in a data center, then the \s-1TPM\s0 migration key must be
 238 available at all the destinations, so in effect it may have to be a key shared across
 239 all machines in the datacenter. In contrast to that, the key used for encrypting the
 240 \&\s-1TPM\s0 state <B>files<B> can be different for each \s-1TPM\s0 and need only be available
 241 on the host where the \s-1TPM\s0 state resides.
 242 .Sp
 243 The migration key enables the encryption of the \s-1TPM\s0 state blobs.
 244 The keyfile must contain an \s-1AES\s0 key of supported size; 128 bit (16 bytes)
 245 and 256 bit (32 bytes) keys are supported.
 246 .Sp
 247 The key may be in binary format, in which case the file size must be 16 or
 248 32 bytes. If the key is in hex format (default), the key may consist of 32
 249 or 64 hex digits starting with an optional '0x'.
 250 .Sp
 251 The \fImode\fR parameter indicates which block chaining mode is to be used.
 252 Currently aes-cbc (aes\-128\-cbc) and aes\-256\-cbc are supported.
 253 The encrypted data is integrity protected using encrypt-then-mac.
 254 .Sp
 255 The \fIremove\fR parameter will attempt to remove the given keyfile once the key
 256 has been read.
 257 .IP "\fB\-\-migration\-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]\fR" 4
 258 .IX Item "--migration-key pwdfile=<passphrase file>|pwdfd=<fd>[,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,kdf=sha512|pbkdf2]"
 259 This variant of the key parameter allows to provide a passphrase in a file.
 260 The file is read and a key is derived from it using either a \s-1SHA512\s0 hash
 261 or \s-1PBKDF2.\s0 By default \s-1PBKDF2\s0 is used.
 262 .IP "\fB\-\-pid file=<pidfile>\fR|fd=<filedescriptor>>" 4
 263 .IX Item "--pid file=<pidfile>|fd=<filedescriptor>>"
 264 This options allows to set the name of file where the process \s-1ID\s0 (pid) of the \s-1CUSE TPM\s0
 265 will be written into. The file will be written by the root user. It is also possible to
 266 pass a file descriptor to a file that has been opened for writing.
 267 .IP "\fB\-\-seccomp action=none|log|kill\fR (since v0.2)" 4
 268 .IX Item "--seccomp action=none|log|kill (since v0.2)"
 269 This option allows to select the action to take by the seccomp profile when
 270 a syscall is executed that is not allowed. The default is \fIkill\fR. To disable
 271 the seccomp profile, choose \fInone\fR. The \fIlog\fR action logs offending syscalls.
 272 The \fIlog\fR action is only available if libseccomp supports logging.
 273 .Sp
 274 This option is only available on Linux and only if swtpm was compiled with
 275 libseccomp support.
 276 .IP "\fB\-\-print\-capabilities\fR (since v0.2)" 4
 277 .IX Item "--print-capabilities (since v0.2)"
 278 Print capabilities that were added to swtpm after version 0.1. The output
 279 may contain the following:
 280 .Sp
 281 .Vb 7
 282 \&    {
 283 \&      "type": "swtpm",
 284 \&      "features": [
 285 \&        "cmdarg\-seccomp",
 286 \&        "cmdarg\-key\-fd"
 287 \&      ]
 288 \&    }
 289 .Ve
 290 .Sp
 291 The meaning of the feature verbs is as follows:
 292 .RS 4
 293 .IP "\fBcmdarg-seccomp\fR" 4
 294 .IX Item "cmdarg-seccomp"
 295 The \fI\-\-seccomp\fR option is supported.
 296 .IP "\fBcmdarg-key-fd\fR" 4
 297 .IX Item "cmdarg-key-fd"
 298 The \fI\-\-key\fR option supports the \fIfd=\fR parameter.
 299 .RE
 300 .RS 4
 301 .RE
 302 .SH "EXAMPLES"
 303 .IX Header "EXAMPLES"
 304 To start the \s-1CUSE TPM\s0 and have it create the character device /dev/foo,
 305 use the following commands:
 306 .Sp
 307 .Vb 1
 308 \& # ensure that previous swtpm_cuse using /dev/foo is gone
 309 \&
 310 \& swtpm_ioctl \-s /dev/foo
 311 \&
 312 \& # Start the swtpm with TPM 2 functionality and make it accessible
 313 \& # through /dev/foo. Have the swtpm_cuse write the TPM\*(Aqs persistent
 314 \& # state into the given directory.
 315 \&
 316 \& export TPM_PATH=/tmp/foo
 317 \& mkdir \-p $TPM_PATH
 318 \&
 319 \& swtpm_cuse \-n foo \-\-tpm2
 320 \&
 321 \& # Send TPM_Init to the TPM; this is absolutely necessary
 322 \&
 323 \& swtpm_ioctl \-i /dev/foo
 324 .Ve
 325 .SH "SEE ALSO"
 326 .IX Header "SEE ALSO"
 327 \&\fBswtpm_bios\fR, \fBswtpm_ioctl\fR