1tpm2_hmac(1) General Commands Manual tpm2_hmac(1)
2
3
4
6 tpm2_hmac(1) - Performs an HMAC operation with the TPM.
7
9 tpm2_hmac [OPTIONS] [ARGUMENT]
10
12 tpm2_hmac(1) - Performs an HMAC operation and returns the results. If
13 argument file is not specified, then data is read from stdin.
14
15 The hashing algorithm defaults to the keys scheme or sha256 if the key
16 has a NULL scheme.
17
18 Output defaults to STDOUT and binary format unless otherwise specified
19 via -o and –hex options respectively.
20
22 • -c, --key-context=OBJECT:
23
24 The context object of the symmetric signing key providing the HMAC
25 key. Either a file or a handle number. See section “Context Object
26 Format”.
27
28 • -p, --auth=AUTH:
29
30 Optional authorization value to use the key specified by -c.
31
32 • -g, --hash-algorithm=ALGORITHM:
33
34 The hash algorithm to use. Algorithms should follow the “formatting
35 standards”, see section “Algorithm Specifiers”. Also, see section
36 “Supported Hash Algorithms” for a list of supported hash algorithms.
37
38 • --hex
39
40 Convert the output hmac to hex format without a leading “0x”.
41
42 • -o, --output=FILE:
43
44 Optional file record of the HMAC result. Defaults to STDOUT.
45
46 • -t, --ticket=FILE:
47
48 Optional file record of the ticket result.
49
50 • --cphash=FILE
51
52 File path to record the hash of the command parameters. This is com‐
53 monly termed as cpHash. NOTE: When this option is selected, The tool
54 will not actually execute the command, it simply returns a cpHash.
55
56 • ARGUMENT the command line argument specifies the file path for the
57 data to HMAC. Defaults to STDIN if not specified.
58
59 References
61 The type of a context object, whether it is a handle or file name, is
62 determined according to the following logic in-order:
63
64 • If the argument is a file path, then the file is loaded as a restored
65 TPM transient object.
66
67 • If the argument is a prefix match on one of:
68
69 • owner: the owner hierarchy
70
71 • platform: the platform hierarchy
72
73 • endorsement: the endorsement hierarchy
74
75 • lockout: the lockout control persistent object
76
77 • If the argument argument can be loaded as a number it will be treat
78 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
79
81 Authorization for use of an object in TPM2.0 can come in 3 different
82 forms: 1. Password 2. HMAC 3. Sessions
83
84 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
85 fied”.
86
87 Passwords
88 Passwords are interpreted in the following forms below using prefix
89 identifiers.
90
91 Note: By default passwords are assumed to be in the string form when
92 they do not have a prefix.
93
94 String
95 A string password, specified by prefix “str:” or it’s absence (raw
96 string without prefix) is not interpreted, and is directly used for au‐
97 thorization.
98
99 Examples
100 foobar
101 str:foobar
102
103 Hex-string
104 A hex-string password, specified by prefix “hex:” is converted from a
105 hexidecimal form into a byte array form, thus allowing passwords with
106 non-printable and/or terminal un-friendly characters.
107
108 Example
109 hex:0x1122334455667788
110
111 File
112 A file based password, specified be prefix “file:” should be the path
113 of a file containing the password to be read by the tool or a “-” to
114 use stdin. Storing passwords in files prevents information leakage,
115 passwords passed as options can be read from the process list or common
116 shell history features.
117
118 Examples
119 # to use stdin and be prompted
120 file:-
121
122 # to use a file from a path
123 file:path/to/password/file
124
125 # to echo a password via stdin:
126 echo foobar | tpm2_tool -p file:-
127
128 # to use a bash here-string via stdin:
129
130 tpm2_tool -p file:- <<< foobar
131
132 Sessions
133 When using a policy session to authorize the use of an object, prefix
134 the option argument with the session keyword. Then indicate a path to
135 a session file that was created with tpm2_startauthsession(1). Option‐
136 ally, if the session requires an auth value to be sent with the session
137 handle (eg policy password), then append a + and a string as described
138 in the Passwords section.
139
140 Examples
141 To use a session context file called session.ctx.
142
143 session:session.ctx
144
145 To use a session context file called session.ctx AND send the authvalue
146 mypassword.
147
148 session:session.ctx+mypassword
149
150 To use a session context file called session.ctx AND send the HEX auth‐
151 value 0x11223344.
152
153 session:session.ctx+hex:11223344
154
155 PCR Authorizations
156 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
157 language. The PCR minilanguage is as follows:
158 <pcr-spec>=<raw-pcr-file>
159
160 The PCR spec is documented in in the section “PCR bank specifiers”.
161
162 The raw-pcr-file is an optional argument that contains the output of
163 the raw PCR contents as returned by tpm2_pcrread(1).
164
165 PCR bank specifiers (pcr.md)
166
167 Examples
168 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
169 er of:
170
171 pcr:sha256:0,1,2,3
172
173 specifying AUTH.
174
176 Authorization for use of an object in TPM2.0 can come in 3 different
177 forms: 1. Password 2. HMAC 3. Sessions
178
179 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
180 fied”.
181
182 Passwords
183 Passwords are interpreted in the following forms below using prefix
184 identifiers.
185
186 Note: By default passwords are assumed to be in the string form when
187 they do not have a prefix.
188
189 String
190 A string password, specified by prefix “str:” or it’s absence (raw
191 string without prefix) is not interpreted, and is directly used for au‐
192 thorization.
193
194 Examples
195 foobar
196 str:foobar
197
198 Hex-string
199 A hex-string password, specified by prefix “hex:” is converted from a
200 hexidecimal form into a byte array form, thus allowing passwords with
201 non-printable and/or terminal un-friendly characters.
202
203 Example
204 hex:0x1122334455667788
205
206 File
207 A file based password, specified be prefix “file:” should be the path
208 of a file containing the password to be read by the tool or a “-” to
209 use stdin. Storing passwords in files prevents information leakage,
210 passwords passed as options can be read from the process list or common
211 shell history features.
212
213 Examples
214 # to use stdin and be prompted
215 file:-
216
217 # to use a file from a path
218 file:path/to/password/file
219
220 # to echo a password via stdin:
221 echo foobar | tpm2_tool -p file:-
222
223 # to use a bash here-string via stdin:
224
225 tpm2_tool -p file:- <<< foobar
226
227 Sessions
228 When using a policy session to authorize the use of an object, prefix
229 the option argument with the session keyword. Then indicate a path to
230 a session file that was created with tpm2_startauthsession(1). Option‐
231 ally, if the session requires an auth value to be sent with the session
232 handle (eg policy password), then append a + and a string as described
233 in the Passwords section.
234
235 Examples
236 To use a session context file called session.ctx.
237
238 session:session.ctx
239
240 To use a session context file called session.ctx AND send the authvalue
241 mypassword.
242
243 session:session.ctx+mypassword
244
245 To use a session context file called session.ctx AND send the HEX auth‐
246 value 0x11223344.
247
248 session:session.ctx+hex:11223344
249
250 PCR Authorizations
251 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
252 language. The PCR minilanguage is as follows:
253 <pcr-spec>=<raw-pcr-file>
254
255 The PCR spec is documented in in the section “PCR bank specifiers”.
256
257 The raw-pcr-file is an optional argument that contains the output of
258 the raw PCR contents as returned by tpm2_pcrread(1).
259
260 PCR bank specifiers (pcr.md)
261
262 Examples
263 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
264 er of:
265
266 pcr:sha256:0,1,2,3
267
268 ALGORITHM.
269
271 This collection of options are common to many programs and provide in‐
272 formation that many users may expect.
273
274 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
275 attempts to invoke the manpager for the tool, however, on failure
276 will output a short tool summary. This is the same behavior if the
277 “man” option argument is specified, however if explicit “man” is re‐
278 quested, the tool will provide errors from man on stderr. If the
279 “no-man” option if specified, or the manpager fails, the short op‐
280 tions will be output to stdout.
281
282 To successfully use the manpages feature requires the manpages to be
283 installed or on MANPATH, See man(1) for more details.
284
285 • -v, --version: Display version information for this tool, supported
286 tctis and exit.
287
288 • -V, --verbose: Increase the information that the tool prints to the
289 console during its execution. When using this option the file and
290 line number are printed.
291
292 • -Q, --quiet: Silence normal tool output to stdout.
293
294 • -Z, --enable-errata: Enable the application of errata fixups. Useful
295 if an errata fixup needs to be applied to commands sent to the TPM.
296 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
297 formation many users may expect.
298
300 The TCTI or “Transmission Interface” is the communication mechanism
301 with the TPM. TCTIs can be changed for communication with TPMs across
302 different mediums.
303
304 To control the TCTI, the tools respect:
305
306 1. The command line option -T or --tcti
307
308 2. The environment variable: TPM2TOOLS_TCTI.
309
310 Note: The command line option always overrides the environment vari‐
311 able.
312
313 The current known TCTIs are:
314
315 • tabrmd - The resource manager, called tabrmd
316 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
317 abrmd as a tcti name are synonymous.
318
319 • mssim - Typically used for communicating to the TPM software simula‐
320 tor.
321
322 • device - Used when talking directly to a TPM device file.
323
324 • none - Do not initalize a connection with the TPM. Some tools allow
325 for off-tpm options and thus support not using a TCTI. Tools that do
326 not support it will error when attempted to be used without a TCTI
327 connection. Does not support ANY options and MUST BE presented as
328 the exact text of “none”.
329
330 The arguments to either the command line option or the environment
331 variable are in the form:
332
333 <tcti-name>:<tcti-option-config>
334
335 Specifying an empty string for either the <tcti-name> or <tcti-op‐
336 tion-config> results in the default being used for that portion respec‐
337 tively.
338
339 TCTI Defaults
340 When a TCTI is not specified, the default TCTI is searched for using
341 dlopen(3) semantics. The tools will search for tabrmd, device and
342 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
343 what TCTI will be chosen as the default by using the -v option to print
344 the version information. The “default-tcti” key-value pair will indi‐
345 cate which of the aforementioned TCTIs is the default.
346
347 Custom TCTIs
348 Any TCTI that implements the dynamic TCTI interface can be loaded. The
349 tools internally use dlopen(3), and the raw tcti-name value is used for
350 the lookup. Thus, this could be a path to the shared library, or a li‐
351 brary name as understood by dlopen(3) semantics.
352
354 This collection of options are used to configure the various known TCTI
355 modules available:
356
357 • device: For the device TCTI, the TPM character device file for use by
358 the device TCTI can be specified. The default is /dev/tpm0.
359
360 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
361 vice:/dev/tpm0”
362
363 • mssim: For the mssim TCTI, the domain name or IP address and port
364 number used by the simulator can be specified. The default are
365 127.0.0.1 and 2321.
366
367 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
368 TI=“mssim:host=localhost,port=2321”
369
370 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
371 ries of simple key value pairs separated by a `,' character. Each
372 key and value string are separated by a `=' character.
373
374 • TCTI abrmd supports two keys:
375
376 1. `bus_name' : The name of the tabrmd service on the bus (a
377 string).
378
379 2. `bus_type' : The type of the dbus instance (a string) limited to
380 `session' and `system'.
381
382 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
383 ample.FooBar:
384
385 \--tcti=tabrmd:bus_name=com.example.FooBar
386
387 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
388 sion:
389
390 \--tcti:bus_type=session
391
392 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
393 ules.
394
396 Setup
397 # create a primary object
398 tpm2_createprimary -c primary.ctx
399
400 # create an hmac key
401 tpm2_create -C primary.ctx -G hmac -c hmac.key
402
403 Perform an HMAC with Default Hash Algorithm
404 Perform an hmac using the key’s default scheme (hash algorithm) and
405 output to stdout in hexidecimal format.
406
407 tpm2_hmac -c hmac.key --hex data.in
408 e6eda48a53a9ddbb92f788f6d98e0372d63a408afb11aca43f522a2475a32805
409
411 Tools can return any of the following codes:
412
413 • 0 - Success.
414
415 • 1 - General non-specific error.
416
417 • 2 - Options handling error.
418
419 • 3 - Authentication error.
420
421 • 4 - TCTI related error.
422
423 • 5 - Non supported scheme. Applicable to tpm2_testparams.
424
426 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
427
429 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
430
431
432
433tpm2-tools tpm2_hmac(1)