.\" 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 8" .TH swtpm 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 \- TPM Emulator for TPM 1.2 and 2.0 .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBswtpm socket [\s-1OPTIONS\s0]\fR .PP \&\fBswtpm chardev [\s-1OPTIONS\s0]\fR .PP \&\fBswtpm cuse [\s-1OPTIONS\s0]\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBswtpm\fR implements a \s-1TPM\s0 software emulator built on libtpms. It provides access to \s-1TPM\s0 functionality over a \s-1TCP/IP\s0 socket interface or it can listend for commands on a character device, or create a \s-1CUSE\s0 (character device in userspace) interface for receiving of \s-1TPM\s0 commands. .PP Unless corresponding command line parameters are used, the \&\fBswtpm\fR socket version requires that the environment variable \fI\s-1TPM_PORT\s0\fR be set to the \s-1TCP/IP\s0 port the process is supposed to listen on for \s-1TPM\s0 request messages. .PP Similarly, the environment variable \fI\s-1TPM_PATH\s0\fR can be set and contain the name of a directory where the \s-1TPM\s0 can store its persistent state into. .PP The \fBswtpm\fR process can be gracefully terminated by sending a \&\fI\s-1SIGTERM\s0\fR signal to it. .PP The \fBswtpm\fR cuse version requires root rights to start the \s-1TPM.\s0 .SH "Options for socket interface" .IX Header "Options for socket interface" The following options are supported if the \fIsocket\fR interface is chosen: .IP "\fB\-p|\-\-port " 4 .IX Item "-p|--port " Use the given port rather than using the environment variable \s-1TPM_PORT.\s0 .IP "\fB\-t|\-\-terminate\fR" 4 .IX Item "-t|--terminate" Terminate the \s-1TPM\s0 after the client has closed the connection. .IP "\fB\-\-server [type=tcp][,port=[,bindaddr=
[,ifname=]]][,fd=][,disconnect]\fR" 4 .IX Item "--server [type=tcp][,port=[,bindaddr=
[,ifname=]]][,fd=][,disconnect]" Expect \s-1TCP\s0 connections on the given port; if a port is not provided a file descriptor must be passed with the fd parameter and the commands are read from this file descriptor then. If a port is provided the \fIbind address\fR on which to listen for \s-1TCP\s0 connections can be provided as well; the default bind address is 127.0.0.1. If a link local IPv6 address is provided, the name of the interface to bind to must be provided with \fIifname\fR. .Sp This parameter enables a persistent connection by default unless the disconnect option is given. This parameter should be used rather than the \-p and \-\-fd options. .IP "\fB\-\-server type=unixio[,path=][,fd=] [,mode=<0...>][,uid=][,gid=]\fR" 4 .IX Item "--server type=unixio[,path=][,fd=] [,mode=<0...>][,uid=][,gid=]" Expect UnixIO connections on the given path. If no path is provided, a file descriptor must be passed instead. The mode parameter allows a user to set the file mode bits of the UnixIO path. The mode bits value must be given as an octal number starting with a '0'. The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. This operation requires root privileges. .SH "Options for character device interface" .IX Header "Options for character device interface" The following options are supported if the \fIchardev\fR interface is chosen: .IP "\fB\-c|\-\-chardev " 4 .IX Item "-c|--chardev " Use the given device to listen for \s-1TPM\s0 commands and send response on. .IP "\fB\-\-vtpm\-proxy\fR" 4 .IX Item "--vtpm-proxy" Create a Linux vTPM proxy device instance and read \s-1TPM\s0 commands from its backend device. .SH "Options for the CUSE interface" .IX Header "Options for the CUSE interface" The following options are supported if the \fIcuse\fR interface is chosen: .IP "\fB\-n|\-\-name <\s-1NAME\s0\fR>" 4 .IX Item "-n|--name " The \s-1TPM\s0 will use a device with the given name. A device with the given name will be created in /dev. This is a mandatory option. .IP "\fB\-M|\-\-maj <\s-1MAJOR\s0\fR>" 4 .IX Item "-M|--maj " Create the device with the given major number. .IP "\fB\-m|\-\-min <\s-1MINOR\s0\fR>" 4 .IX Item "-m|--min " Create the device with the given minor number. .SH "Options for socket and character device interfaces:" .IX Header "Options for socket and character device interfaces:" The following options are supported by the socket and character device interfaces: .IP "\fB\-f|\-\-fd " 4 .IX Item "-f|--fd " Use the given socket file descriptor or character device file descriptor for receiving \s-1TPM\s0 commands and sending responses. For the socket interface, this option automatically assumes \-t. .IP "\fB\-d|\-\-daemon\fR" 4 .IX Item "-d|--daemon" Daemonize the process. .IP "\fB\-\-ctrl type=[unixio|tcp][,path=] [,port=[,bindaddr=
[,ifname=]]] [,fd=|clientfd=] [,mode=<0...>][,uid=][,gid=] \fR" 4 .IX Item "--ctrl type=[unixio|tcp][,path=] [,port=[,bindaddr=
[,ifname=]]] [,fd=|clientfd=] [,mode=<0...>][,uid=][,gid=] " This option adds a control channel to the \s-1TPM.\s0 The control channel can either use a UnixIO socket with a given \fIpath\fR or \fIfiledescriptor\fR or it can use a \s-1TCP\s0 socket on the given \fIport\fR or \fIfiledescriptor\fR. If a port is provided the \fIbind address\fR on which to listen for \s-1TCP\s0 connections can be provided as well; the default bind address is 127.0.0.1. If a link local IPv6 address is provided, the name of the interface to bind to must be provided with \fIifname\fR. .Sp The mode parameter allows a user to set the file mode bits of the UnixIO path. The mode bits value must be given as an octal number starting with a '0'. The default value is 0770. uid and gid set the ownership of the UnixIO socket's path. This operation requires root privileges. .Sp The control channel enables out-of-band control of the \s-1TPM,\s0 such as resetting the \s-1TPM.\s0 .SH "Options for all interfaces" .IX Header "Options for all interfaces" The following options are support by all interfaces: .IP "\fB\-\-tpmstate dir=[,mode=<0...>]|backend\-uri=\fR" 4 .IX Item "--tpmstate dir=[,mode=<0...>]|backend-uri=" Use the given path rather than using the environment variable \s-1TPM_PATH.\s0 .Sp If \fIdir\fR is specified, the \s-1TPM\s0 state files will be written to the \fIdir\fR with the given file \fImode\fR bits. This value must be given as an octal number starting with a '0'. The default value is 0640. .Sp If \fIbackend-uri\fR is specified, the \s-1TPM\s0 state data will be stored to the \s-1URI.\s0 Currently \fIbackend\-uri=dir:// and \fIbackend\-uri=file:// are available. For 'dir://', the \s-1URI\s0 should specify the path to the directory where files are stored. If \fIpath_to_dir\fR starts with a '/' then the path is interpreted as an absolute path, otherwise it is a path relative to the current directory. For 'file://', the \s-1URI\s0 should specify a single file or block device where \s-1TPM\s0 state will be stored. A blockdevice must exist already and be big enough to store all state. (since v0.7) .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\-\-log [fd=|file=][,level=] [,prefix=][,truncate]\fR" 4 .IX Item "--log [fd=|file=][,level=] [,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 a user 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 explicitly 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=|fd= [,format=][,mode=aes\-cbc|aes\-256\-cbc], [remove[=true|false]]\fR" 4 .IX Item "--key file=|fd= [,format=][,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=|pwdfd= [,mode=aes\-cbc|aes\-256\-cbc][remove[=true|false]][,kdf=sha512|pbkdf2]\fR" 4 .IX Item "--key pwdfile=|pwdfd= [,mode=aes-cbc|aes-256-cbc][remove[=true|false]][,kdf=sha512|pbkdf2]" This variant of the key parameter allows a user 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=|fd= [,format=][,mode=aes\-cbc|aes\-256\-cbc] [,remove[=true|false]]\fR" 4 .IX Item "--migration-key file=|fd= [,format=][,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 when the \s-1TPM\s0 state blobs are retrieved through the ioctl interface. The migration key is not used for encrypting \s-1TPM\s0 state written to files, this is what the \fI\-\-key\fR 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 \fBfiles\fR 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=|pwdfd= [,mode=aes\-cbc|aes\-256\-cbc][,remove[=true|false]][,pdf=sha512|pbkdf2]\fR" 4 .IX Item "--migration-key pwdfile=|pwdfd= [,mode=aes-cbc|aes-256-cbc][,remove[=true|false]][,pdf=sha512|pbkdf2]" This variant of the key parameter allows a user 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=|fd=\fR" 4 .IX Item "--pid file=|fd=" This options allows a user to set the name of file where the process \s-1ID\s0 (pid) of the \s-1TPM\s0 will be written into. It is also possible to pass a file descriptor to a file that has been opened for writing. .IP "\fB\-r|\-\-runas \fR" 4 .IX Item "-r|--runas " Switch to the given user. This option can only be used when swtpm is started as root. .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 a user 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\-\-flags [not\-need\-init] [,startup\-clear|startup\-state|startup\-deactivated|startup\-none]\fR" 4 .IX Item "--flags [not-need-init] [,startup-clear|startup-state|startup-deactivated|startup-none]" The \fInot-need-init\fR flag enables the \s-1TPM\s0 to accept \s-1TPM\s0 commands right after start without requiring an \s-1INIT\s0 to be sent to it through the command channel (see the '\-i' option of swtpm_ioctl). .Sp The \fIstartup\fR options cause a TPM_Startup or TPM2_Startup command to automatically be sent. The \fIstartup-deactivated\fR option is only valid for a \s-1TPM 1.2.\s0 These options imply \fInot-need-init\fR, except for the \&\fIstartup-none\fR option, which results in no command being sent. .Sp If \fI\-\-vtpm\-proxy\fR is used, \fIstartup-clear\fR is automatically chosen but this can be changed with this option. .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 10 \& { \& "type": "swtpm", \& "features": [ \& "tpm\-1.2", \& "tpm\-2.0", \& "cmdarg\-seccomp", \& "cmdarg\-key\-fd", \& "cmdarg\-pwd\-fd", \& "cmdarg\-print\-states", \& "nvram\-backend\-dir", \& "nvram\-backend\-file", \& "tpm\-send\-command\-header", \& "flags\-opt\-startup", \& "rsa\-keysize\-1024", \& "rsa\-keysize\-2048", \& "rsa\-keysize\-3072" \& ], \& "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 "\fBtpm\-1.2\fR (since v0.7)" 4 .IX Item "tpm-1.2 (since v0.7)" \&\s-1TPM 1.2\s0 emulation is supported (libtpms is compiled with 1.2 support). .IP "\fBtpm\-2.0\fR (since v0.7)" 4 .IX Item "tpm-2.0 (since v0.7)" \&\s-1TPM 2\s0 emulation is supported (libtpms is compiled with 2.0 support). .Sp (the \fI\-\-tpm2\fR option is supported) .IP "\fBcmdarg-seccomp\fR (since v0.2)" 4 .IX Item "cmdarg-seccomp (since v0.2)" The \fI\-\-seccomp\fR option is supported. .IP "\fBcmdarg-key-fd\fR (since v0.2)" 4 .IX Item "cmdarg-key-fd (since v0.2)" The \fI\-\-key\fR option supports the \fIfd=\fR parameter. .IP "\fBcmdarg-pwd-fd\fR (since v0.2)" 4 .IX Item "cmdarg-pwd-fd (since v0.2)" The \fI\-\-key\fR option supports the \fIpwdfd=\fR parameter. .IP "\fBcmdarg-print-states\fR (since v0.7)" 4 .IX Item "cmdarg-print-states (since v0.7)" The \fI\-\-print\-states\fR option is supported. .IP "\fBnvram-backend-dir\fR (since v0.7)" 4 .IX Item "nvram-backend-dir (since v0.7)" The \fI\-\-tpmstate\fR option supports the \fIbackend\-uri=dir://...\fR parameter. .IP "\fBnvram-backend-file\fR (since v0.7)" 4 .IX Item "nvram-backend-file (since v0.7)" The \fI\-\-tpmstate\fR option supports the \fIbackend\-uri=file://...\fR parameter. .IP "\fBtpm-send-command-header\fR (since v0.2)" 4 .IX Item "tpm-send-command-header (since v0.2)" The \s-1TPM 2\s0 commands may be prefixed by a header that carries a 4\-byte command, 1 byte for locality, and 4\-byte \s-1TPM 2\s0 command length indicator. The \s-1TPM 2\s0 will respond by preprending a 4\-byte response indicator and a 4\-byte trailer. All data is sent in big endian format. .IP "\fBflags-opt-startup\fR (since v0.3)" 4 .IX Item "flags-opt-startup (since v0.3)" The \fI\-\-flags\fR option supports the \fIstartup\-...\fR options. .IP "\fBrsa\-keysize\-2048\fR (since v0.4)" 4 .IX Item "rsa-keysize-2048 (since v0.4)" The \s-1TPM 2\s0 supports the shown \s-1RSA\s0 key sizes. If none of the rsa-keysize verbs is shown then only \s-1RSA 2048\s0 bit keys are supported. .RE .RS 4 .RE .IP "\fB\-\-print\-states\fR (since v0.7)" 4 .IX Item "--print-states (since v0.7)" This option allows to print out the \s-1TPM 1.2\s0 or \s-1TPM 2\s0 state blobs that are currently stored in a storage backend. This option requires that the storage backend be specified using the \fI\-\-tpmstate\fR option and if \s-1TPM 2\s0 state blobs are supposed to be shown, the \fI\-\-tpm2\fR option must be passed. .Sp The following shows the \s-1JSON\s0 output of this option. It indicates that the 'permall' and 'volatile' states are available. .Sp .Vb 12 \& { \& "type": "swtpm", \& "states": [ \& { \& "name": "permall", \& "size": 6013 \& }, { \& "name": "volatile", \& "size": 1087 \& } \& ] \& } .Ve .IP "\fB\-h|\-\-help\fR" 4 .IX Item "-h|--help" Display usage info. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBswtpm_bios\fR, \fBswtpm_cuse\fR