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

NAME

6       tpm2_hash(1) - Performs a hash operation with the TPM.
7

SYNOPSIS

9       tpm2_hash [OPTIONS] [ARGUMENT OR STDIN]
10

DESCRIPTION

12       tpm2_hash(1)  -  Performs  a hash operation on file and returns the re‐
13       sults.  If argument is not specified, then data is read from stdin.  If
14       the results of the hash will be used in a signing operation that uses a
15       restricted signing key, then the ticket returned by  this  command  can
16       indicate that the hash is safe to sign.
17
18       Output  defaults to stdout and binary format unless otherwise specified
19       via -o and –hex options respectively.
20

OPTIONS

22-C, --hierarchy=OBJECT:
23         Hierarchy to use for the ticket.  Defaults to o,  TPM_RH_OWNER,  when
24         no value has been specified.  Supported options are:
25
26o for TPM_RH_OWNER
27
28p for TPM_RH_PLATFORM
29
30e for TPM_RH_ENDORSEMENT
31
32n for TPM_RH_NULL
33
34-g, --hash-algorithm=ALGORITHM:
35
36         The hashing algorithm for the digest operation.
37
38--hex
39
40         Convert the output hmac to hex format without a leading “0x”.
41
42-o, --output=FILE or STDOUT:
43
44         Optional  file  to  save  the hash result.  Defaults to stdout in hex
45         form.
46
47-t, --ticket=TICKET_FILE
48
49         Optional file record of the ticket result.  Defaults to stdout in hex
50         form.
51
52ARGUMENT  or  STDIN  the  command line argument specifies the FILE to
53         hash.
54
55   References

Context Object Format

57       The type of a context object, whether it is a handle or file  name,  is
58       determined according to the following logic in-order:
59
60       • If the argument is a file path, then the file is loaded as a restored
61         TPM transient object.
62
63       • If the argument is a prefix match on one of:
64
65         • owner: the owner hierarchy
66
67         • platform: the platform hierarchy
68
69         • endorsement: the endorsement hierarchy
70
71         • lockout: the lockout control persistent object
72
73       • If the argument argument can be loaded as a number it will  be  treat
74         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
75

Authorization Formatting

77       Authorization  for  use  of an object in TPM2.0 can come in 3 different
78       forms: 1.  Password 2.  HMAC 3.  Sessions
79
80       NOTE: “Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
81       fied”.
82
83   Passwords
84       Passwords  are  interpreted  in  the following forms below using prefix
85       identifiers.
86
87       Note: By default passwords are assumed to be in the  string  form  when
88       they do not have a prefix.
89
90   String
91       A  string  password,  specified  by  prefix “str:” or it’s absence (raw
92       string without prefix) is not interpreted, and is directly used for au‐
93       thorization.
94
95   Examples
96              foobar
97              str:foobar
98
99   Hex-string
100       A  hex-string  password, specified by prefix “hex:” is converted from a
101       hexidecimal form into a byte array form, thus allowing  passwords  with
102       non-printable and/or terminal un-friendly characters.
103
104   Example
105              hex:1122334455667788
106
107   File
108       A  file  based password, specified be prefix “file:” should be the path
109       of a file containing the password to be read by the tool or  a  “-”  to
110       use  stdin.   Storing  passwords in files prevents information leakage,
111       passwords passed as options can be read from the process list or common
112       shell history features.
113
114   Examples
115              # to use stdin and be prompted
116              file:-
117
118              # to use a file from a path
119              file:path/to/password/file
120
121              # to echo a password via stdin:
122              echo foobar | tpm2_tool -p file:-
123
124              # to use a bash here-string via stdin:
125
126              tpm2_tool -p file:- <<< foobar
127
128   Sessions
129       When  using  a policy session to authorize the use of an object, prefix
130       the option argument with the session keyword.  Then indicate a path  to
131       a session file that was created with tpm2_startauthsession(1).  Option‐
132       ally, if the session requires an auth value to be sent with the session
133       handle  (eg policy password), then append a + and a string as described
134       in the Passwords section.
135
136   Examples
137       To use a session context file called session.ctx.
138
139              session:session.ctx
140
141       To use a session context file called session.ctx AND send the authvalue
142       mypassword.
143
144              session:session.ctx+mypassword
145
146       To use a session context file called session.ctx AND send the HEX auth‐
147       value 0x11223344.
148
149              session:session.ctx+hex:11223344
150
151   PCR Authorizations
152       You can satisfy a PCR policy using the “pcr:” prefix and the PCR  mini‐
153       language.       The     PCR     minilanguage     is     as     follows:
154       <pcr-spec>=<raw-pcr-file>
155
156       The PCR spec is documented in in the section “PCR bank specifiers”.
157
158       The raw-pcr-file is an optional argument that contains  the  output  of
159       the raw PCR contents as returned by tpm2_pcrread(1).
160
161       PCR bank specifiers (pcr.md)
162
163   Examples
164       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
165       er of:
166
167              pcr:sha256:0,1,2,3
168
169       ALGORITHM.
170

COMMON OPTIONS

172       This collection of options are common to many programs and provide  in‐
173       formation that many users may expect.
174
175-h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
176         attempts to invoke the manpager for the  tool,  however,  on  failure
177         will  output  a short tool summary.  This is the same behavior if the
178         “man” option argument is specified, however if explicit “man” is  re‐
179         quested,  the  tool  will  provide errors from man on stderr.  If the
180         “no-man” option if specified, or the manpager fails,  the  short  op‐
181         tions will be output to stdout.
182
183         To  successfully use the manpages feature requires the manpages to be
184         installed or on MANPATH, See man(1) for more details.
185
186-v, --version: Display version information for this  tool,  supported
187         tctis and exit.
188
189-V,  --verbose:  Increase the information that the tool prints to the
190         console during its execution.  When using this option  the  file  and
191         line number are printed.
192
193-Q, --quiet: Silence normal tool output to stdout.
194
195-Z, --enable-errata: Enable the application of errata fixups.  Useful
196         if an errata fixup needs to be applied to commands sent to  the  TPM.
197         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
198         formation many users may expect.
199

TCTI Configuration

201       The TCTI or “Transmission Interface”  is  the  communication  mechanism
202       with  the TPM.  TCTIs can be changed for communication with TPMs across
203       different mediums.
204
205       To control the TCTI, the tools respect:
206
207       1. The command line option -T or --tcti
208
209       2. The environment variable: TPM2TOOLS_TCTI.
210
211       Note: The command line option always overrides  the  environment  vari‐
212       able.
213
214       The current known TCTIs are:
215
216       • tabrmd      -     The     resource     manager,     called     tabrmd
217         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
218         abrmd as a tcti name are synonymous.
219
220       • mssim  - Typically used for communicating to the TPM software simula‐
221         tor.
222
223       • device - Used when talking directly to a TPM device file.
224
225       • none - Do not initalize a connection with the TPM.  Some tools  allow
226         for off-tpm options and thus support not using a TCTI.  Tools that do
227         not support it will error when attempted to be used  without  a  TCTI
228         connection.   Does  not  support ANY options and MUST BE presented as
229         the exact text of “none”.
230
231       The arguments to either the command  line  option  or  the  environment
232       variable are in the form:
233
234       <tcti-name>:<tcti-option-config>
235
236       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
237       tion-config> results in the default being used for that portion respec‐
238       tively.
239
240   TCTI Defaults
241       When  a  TCTI  is not specified, the default TCTI is searched for using
242       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
243       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
244       what TCTI will be chosen as the default by using the -v option to print
245       the  version information.  The “default-tcti” key-value pair will indi‐
246       cate which of the aforementioned TCTIs is the default.
247
248   Custom TCTIs
249       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
250       tools internally use dlopen(3), and the raw tcti-name value is used for
251       the lookup.  Thus, this could be a path to the shared library, or a li‐
252       brary name as understood by dlopen(3) semantics.
253

TCTI OPTIONS

255       This collection of options are used to configure the various known TCTI
256       modules available:
257
258device: For the device TCTI, the TPM character device file for use by
259         the device TCTI can be specified.  The default is /dev/tpm0.
260
261         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
262         vice:/dev/tpm0”
263
264mssim: For the mssim TCTI, the domain name or  IP  address  and  port
265         number  used  by  the  simulator  can  be specified.  The default are
266         127.0.0.1 and 2321.
267
268         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
269         TI=“mssim:host=localhost,port=2321”
270
271abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
272         ries of simple key value pairs separated by a  `,'  character.   Each
273         key and value string are separated by a `=' character.
274
275         • TCTI abrmd supports two keys:
276
277           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
278              string).
279
280           2. `bus_type' : The type of the dbus instance (a string) limited to
281              `session' and `system'.
282
283         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
284         ample.FooBar:
285
286                \--tcti=tabrmd:bus_name=com.example.FooBar
287
288         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
289         sion:
290
291                \--tcti:bus_type=session
292
293         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
294         ules.
295

EXAMPLES

297   Hash a file with sha1 hash algorithm and save the hash and ticket to a file
298              tpm2_hash -C e -g sha1 -o hash.bin -t ticket.bin data.txt
299

Returns

301       Tools can return any of the following codes:
302
303       • 0 - Success.
304
305       • 1 - General non-specific error.
306
307       • 2 - Options handling error.
308
309       • 3 - Authentication error.
310
311       • 4 - TCTI related error.
312
313       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
314

BUGS

316       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
317

HELP

319       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
320       fo/tpm2)
321
322
323
324tpm2-tools                                                        tpm2_hash(1)
Impressum