.\" Automatically generated by Pandoc 2.10.1
.\"
.TH "tpm2-totp" "1" "DECEMBER 2018" "tpm2-totp" "General Commands Manual"
.hy
.SH NAME
.PP
\f[B]tpm2-totp\f[R](1) \[en] generate or calculate TPM based TOTPs
.SH SYNOPSIS
.PP
\f[B]tpm2-totp\f[R] [\f[I]options\f[R]]
.SH DESCRIPTION
.PP
\f[B]tpm2-totp\f[R] creates a key inside a TPM 2.0 that can be used to
generate time-based onetime passwords (TOTPs) to demonstrate to the user
that a platform was not altered during his/her abscense and thus still
trustworthy.
.SH ARGUMENTS
.PP
The \f[C]tpm2-totp\f[R] command expects one of five command and provides
a set of options.
.SS COMMANDS
.IP \[bu] 2
\f[C]generate\f[R]: Generate a new TOTP secret.
Possible options: \f[C]-b\f[R], \f[C]-l\f[R], \f[C]-N\f[R],
\f[C]-p\f[R], \f[C]-P\f[R], \f[C]-T\f[R]
.IP \[bu] 2
\f[C]calculate\f[R]: Calculate a TOTP value.
Possible options: \f[C]-N\f[R], \f[C]-t\f[R], \f[C]-T\f[R]
.IP \[bu] 2
\f[C]reseal\f[R]: Reseal TOTP secret to new PCRs, banks or values.
Possible options: \f[C]-b\f[R], \f[C]-N\f[R], \f[C]-p\f[R], \f[C]-P\f[R]
(required), \f[C]-T\f[R]
.IP \[bu] 2
\f[C]recover\f[R]: Recover the TOTP secret and display it again.
Possible Options: \f[C]-N\f[R], \f[C]-P\f[R] (required), \f[C]-T\f[R]
.IP \[bu] 2
\f[C]clean\f[R]: Delete the consumed NV index.
Possible Options: \f[C]-N\f[R], \f[C]-T\f[R]
.SS OPTIONS
.IP \[bu] 2
\f[C]-b <bank>[,<bank>[,...]]\f[R],
\f[C]--banks <bank>[,<bank>[,...]]\f[R]: Selected PCR banks (default:
SHA1,SHA256)
.IP \[bu] 2
\f[C]-h\f[R], \f[C]--help\f[R]: Print help
.IP \[bu] 2
\f[C]-l\f[R], \f[C]--label\f[R]: Label to use for display in the TOTP
authenticator app (default: TPM2-TOTP)
.IP \[bu] 2
\f[C]-N <nvindex>\f[R], \f[C]--nvindex <nvindex>\f[R]: TPM NV index to
store data (default: 0x018094AF)
.IP \[bu] 2
\f[C]-p <pcr>[,<pcr>[,...]]\f[R], \f[C]--pcrs <pcr>[,<pcr>[,...]]\f[R]:
Selected PCR registers (default: 0,2,4,6)
.IP \[bu] 2
\f[C]-P <password>\f[R], \f[C]--password <password>\f[R]: Password for
the secret (default: none) (commands: generate, recover, reseal)
.IP \[bu] 2
\f[C]-t\f[R], \f[C]--time\f[R]: Display the date/time of the TOTP
calculation (commands: calculate)
.IP \[bu] 2
\f[C]-T <tcti-name>[:<tcti-config>]\f[R],
\f[C]--tcti <tcti-name>[:<tcti-config>]\f[R]: Select the TCTI to use.
\f[I]tcti-name\f[R] is the name of the TCTI library.
If present, the configuration string \f[I]tcti-config\f[R] is passed
verbatim to the chosen TCTI library.
.RS 2
.PP
The TCTI can additionally be specified using the environment variable
\f[C]TPM2TOTP_TCTI\f[R].
If both the command line option and the environment variable are
present, the command line option is used.
.PP
If no TCTI is specified, the default TCTI configured on the system is
used.
.RE
.IP \[bu] 2
\f[C]-v\f[R], \f[C]--verbose\f[R]: Print verbose messages
.SH EXAMPLES
.SS Setup
.PP
The TOTP secret can be generated with and without password.
It is recommended to set a password \f[C]-P\f[R]in order to enable
recovery options.
Also the PCRs and PCR banks can be selected \f[C]-p\f[R] and
\f[C]-b\f[R].
Default values are PCRs \f[C]0,2,4\f[R] and banks
\f[C]SHA1, SHA256\f[R].
.IP
.nf
\f[C]
tpm2-totp generate
tpm2-totp -P verysecret generate
tpm2-totp -P verysecret -p 0,1,2,3,4,5,6 generate
tpm2-totp -p 0,1,2,3,4,5,6 -b SHA1,SHA256 generate
\f[R]
.fi
.SS Boot
.PP
During boot the TOTP value for the current time, together with the
current time should be shown to the user, e.g.\ using plymouth from
mkinitrd or from dracut.
The command to be executed is:
.IP
.nf
\f[C]
tpm2-totp calculate
tpm2-totp -t calculate
\f[R]
.fi
.SS Recovery
.PP
In order to recover the QR code:
.IP
.nf
\f[C]
tpm2-totp -P verysecret recover
\f[R]
.fi
.PP
In order to reseal the secret:
.IP
.nf
\f[C]
tpm2-totp -P verysecret reseal
tpm2-totp -P verysecret -p 1,3,5,6 reseal
\f[R]
.fi
.SS Deletion
.PP
In order to delete the created NV index:
.IP
.nf
\f[C]
tpm2-totp clean
\f[R]
.fi
.SS NV index
.PP
All command additionally take the \f[C]-N\f[R] option to specify the NV
index to be used.
By default, 0x018094AF is used and recommended.
.IP
.nf
\f[C]
tpm2-totp -N 0x01800001 -P verysecret generate
tpm2-totp -N 0x01800001 calculate
tpm2-totp -N 0x01800001 -P verysecret recover
tpm2-totp -N 0x01800001 -P verysecret reseal
\f[R]
.fi
.SS TCTI configuration
.PP
All commands take the \f[C]-T\f[R] option or the \f[C]TPM2TOTP_TCTI\f[R]
environment variable to specify the TCTI to be used.
If the TCTI is not specified explicitly, the default TCTI configured on
the system is used.
To e.g.\ use the TPM simulator bound to a given port, use
.IP
.nf
\f[C]
tpm2-totp -T mssim:port=2321 generate
\f[R]
.fi
.SH RETURNS
.PP
0 on success or 1 on failure.
.SH AUTHOR
.PP
Written by Andreas Fuchs.
.SH COPYRIGHT
.PP
tpm2tss is Copyright (C) 2018 Fraunhofer SIT.
License BSD 3-clause.
.SH SEE ALSO
.PP
tpm2totp_generateKey(3)