1tpm2_pcrevent(1)            General Commands Manual           tpm2_pcrevent(1)
2
3
4

NAME

6       tpm2_pcrevent(1) - Hashes a file and optionally extends a pcr.
7

SYNOPSIS

9       tpm2_pcrevent [OPTIONS] FILE PCR_INDEX
10

DESCRIPTION

12       tpm2_pcrevent(1)  -  Hashes FILE if specified or stdin.  It uses all of
13       the hashing algorithms that the TPM supports.
14
15       Optionally, if a PCR index is specified, it extends that  PCR  for  all
16       supported  algorithms with the hash digest.  FILE and _PCR_INDEX_ argu‐
17       ments don't need to come in any particular order.
18
19       In either case, it outputs to stdout the hash algorithm  used  and  the
20       digest value, one per line:
21
22       alg:digest
23
24       Where  alg  is  the algorithm used (like sha1) and digest is the digest
25       resulting from the hash computation of alg on the data.
26
27       See  sections  23.1  and  sections  17  of  the  TPM2.0   Specification
28       (https://trustedcomputinggroup.org/wp-content/uploads/TPM-
29       Rev-2.0-Part-3-Commands-01.38.pdf)
30

OPTIONS

32       These options control extending the pcr:
33
34       · -P, --auth=AUTH:
35
36         Specifies the authorization value for PCR.
37

COMMON OPTIONS

39       This collection of options are common to many programs and provide  in‐
40       formation that many users may expect.
41
42       · -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
43         attempts to invoke the manpager for the  tool,  however,  on  failure
44         will  output  a short tool summary.  This is the same behavior if the
45         "man" option argument is specified, however if explicit "man" is  re‐
46         quested,  the  tool  will  provide errors from man on stderr.  If the
47         "no-man" option if specified, or the manpager fails,  the  short  op‐
48         tions will be output to stdout.
49
50         To  successfully use the manpages feature requires the manpages to be
51         installed or on MANPATH, See man(1) for more details.
52
53       · -v, --version: Display version information for this  tool,  supported
54         tctis and exit.
55
56       · -V,  --verbose:  Increase the information that the tool prints to the
57         console during its execution.  When using this option  the  file  and
58         line number are printed.
59
60       · -Q, --quiet: Silence normal tool output to stdout.
61
62       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
63         if an errata fixup needs to be applied to commands sent to  the  TPM.
64         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.
65

TCTI Configuration

67       The  TCTI  or  "Transmission  Interface" is the communication mechanism
68       with the TPM.  TCTIs can be changed for communication with TPMs  across
69       different mediums.
70
71       To control the TCTI, the tools respect:
72
73       1. The command line option -T or --tcti
74
75       2. The environment variable: TPM2TOOLS_TCTI.
76
77       Note:  The  command  line option always overrides the environment vari‐
78       able.
79
80       The current known TCTIs are:
81
82       · tabrmd     -     The     resource     manager,     called      tabrmd
83         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
84         abrmd as a tcti name are synonymous.
85
86       · mssim - Typically used for communicating to the TPM software  simula‐
87         tor.
88
89       · device - Used when talking directly to a TPM device file.
90
91       · none  - Do not initalize a connection with the TPM.  Some tools allow
92         for off-tpm options and thus support not using a TCTI.  Tools that do
93         not  support  it  will error when attempted to be used without a TCTI
94         connection.  Does not support ANY options and MUST  BE  presented  as
95         the exact text of "none".
96
97       The  arguments  to  either  the  command line option or the environment
98       variable are in the form:
99
100       <tcti-name>:<tcti-option-config>
101
102       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
103       tion-config> results in the default being used for that portion respec‐
104       tively.
105
106   TCTI Defaults
107       When a TCTI is not specified, the default TCTI is  searched  for  using
108       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
109       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
110       what TCTI will be chosen as the default by using the -v option to print
111       the version information.  The "default-tcti" key-value pair will  indi‐
112       cate which of the aforementioned TCTIs is the default.
113
114   Custom TCTIs
115       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
116       tools internally use dlopen(3), and the raw tcti-name value is used for
117       the lookup.  Thus, this could be a path to the shared library, or a li‐
118       brary name as understood by dlopen(3) semantics.
119

TCTI OPTIONS

121       This collection of options are used to configure the various known TCTI
122       modules available:
123
124       · device: For the device TCTI, the TPM character device file for use by
125         the device TCTI can be specified.  The default is /dev/tpm0.
126
127         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
128         vice:/dev/tpm0"
129
130       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
131         number used by the simulator  can  be  specified.   The  default  are
132         127.0.0.1 and 2321.
133
134         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
135         TI="mssim:host=localhost,port=2321"
136
137       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
138         ries  of  simple  key value pairs separated by a ',' character.  Each
139         key and value string are separated by a '=' character.
140
141         · TCTI abrmd supports two keys:
142
143           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
144              string).
145
146           2. 'bus_type' : The type of the dbus instance (a string) limited to
147              'session' and 'system'.
148
149         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
150         ample.FooBar:
151
152         \--tcti=tabrmd:bus_name=com.example.FooBar
153
154         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
155         sion:
156
157         \--tcti:bus_type=session
158
159         NOTE: abrmd and tabrmd are synonymous.
160

Authorization Formatting

162       Authorization for use of an object in TPM2.0 can come  in  3  different
163       forms: 1.  Password 2.  HMAC 3.  Sessions
164
165       NOTE:  "Authorizations  default  to  the EMPTY PASSWORD when not speci‐
166       fied".
167
168   Passwords
169       Passwords are interpreted in the following  forms  below  using  prefix
170       identifiers.
171
172       Note:  By  default  passwords are assumed to be in the string form when
173       they do not have a prefix.
174
175   String
176       A string password, specified by prefix  "str:"  or  it's  absence  (raw
177       string without prefix) is not interpreted, and is directly used for au‐
178       thorization.
179
180   Examples
181              foobar
182              str:foobar
183
184   Hex-string
185       A hex-string password, specified by prefix "hex:" is converted  from  a
186       hexidecimal  form  into a byte array form, thus allowing passwords with
187       non-printable and/or terminal un-friendly characters.
188
189   Example
190              hex:0x1122334455667788
191
192   File
193       A file based password, specified be prefix "file:" should be  the  path
194       of  a  file  containing the password to be read by the tool or a "-" to
195       use stdin.  Storing passwords in files  prevents  information  leakage,
196       passwords passed as options can be read from the process list or common
197       shell history features.
198
199   Examples
200              # to use stdin and be prompted
201              file:-
202
203              # to use a file from a path
204              file:path/to/password/file
205
206              # to echo a password via stdin:
207              echo foobar | tpm2_tool -p file:-
208
209              # to use a bash here-string via stdin:
210
211              tpm2_tool -p file:- <<< foobar
212
213   Sessions
214       When using a policy session to authorize the use of an  object,  prefix
215       the  option argument with the session keyword.  Then indicate a path to
216       a session file that was created with tpm2_startauthsession(1).  Option‐
217       ally, if the session requires an auth value to be sent with the session
218       handle (eg policy password), then append a + and a string as  described
219       in the Passwords section.
220
221   Examples
222       To use a session context file called session.ctx.
223
224              session:session.ctx
225
226       To use a session context file called session.ctx AND send the authvalue
227       mypassword.
228
229              session:session.ctx+mypassword
230
231       To use a session context file called session.ctx AND send the HEX auth‐
232       value 0x11223344.
233
234              session:session.ctx+hex:11223344
235
236   PCR Authorizations
237       You  can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
238       language.      The     PCR     minilanguage     is     as      follows:
239       <pcr-spec>=<raw-pcr-file>
240
241       The PCR spec is documented in in the section "PCR bank specifiers".
242
243       The  raw-pcr-file  is an optional the output of the raw PCR contents as
244       returned by tpm2_pcrread(1).
245
246       PCR bank specifiers (common/pcr.md)
247
248   Examples
249       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
250       er of:
251
252              pcr:sha256:0,1,2,3
253

EXAMPLES

255   Hash a file
256              echo "foo" > data
257              tpm2_pcrevent data
258
259   Hash a file and extend PCR 8
260              echo "foo" > data
261              tpm2_pcrevent 8 data
262

Returns

264       Tools can return any of the following codes:
265
266       · 0 - Success.
267
268       · 1 - General non-specific error.
269
270       · 2 - Options handling error.
271
272       · 3 - Authentication error.
273
274       · 4 - TCTI related error.
275
276       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
277

BUGS

279       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
280

HELP

282       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
283
284
285
286tpm2-tools                                                    tpm2_pcrevent(1)
Impressum