1tpm2_hash(1) General Commands Manual tpm2_hash(1)
2
3
4
6 tpm2_hash(1) - Performs a hash operation with the TPM.
7
9 tpm2_hash [OPTIONS] [ARGUMENT OR STDIN]
10
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
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
26 · o for TPM_RH_OWNER
27
28 · p for TPM_RH_PLATFORM
29
30 · e for TPM_RH_ENDORSEMENT
31
32 · n 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
52 · ARGUMENT or STDIN the command line argument specifies the FILE to
53 hash.
54
55 References
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
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:0x1122334455667788
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 the output of the raw PCR contents as
159 returned by tpm2_pcrread(1).
160
161 PCR bank specifiers (common/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
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
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
255 This collection of options are used to configure the various known TCTI
256 modules available:
257
258 · device: 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
264 · mssim: 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
271 · abrmd: 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
297 Hash a file with sha1 hash algorithm and save the hash and ticket to
298 a file
299
300 tpm2_hash -C e -g sha1 -o hash.bin -t ticket.bin data.txt
301
303 Tools can return any of the following codes:
304
305 · 0 - Success.
306
307 · 1 - General non-specific error.
308
309 · 2 - Options handling error.
310
311 · 3 - Authentication error.
312
313 · 4 - TCTI related error.
314
315 · 5 - Non supported scheme. Applicable to tpm2_testparams.
316
318 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
319
321 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
322
323
324
325tpm2-tools tpm2_hash(1)