1tpm2_hmac(1) General Commands Manual tpm2_hmac(1)
2
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 The hashing algorithm defaults to the keys scheme or sha256 if the key
16 has a NULL scheme.
17 Output defaults to STDOUT and binary format unless otherwise specified
19 via -o and –hex options respectively.
20
22 • -c, --key-context=OBJECT:
23 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 • -p, --auth=AUTH:
29 Optional authorization value to use the key specified by -c.
31 • -g, --hash-algorithm=ALGORITHM:
33 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 • --hex
39 Convert the output hmac to hex format without a leading “0x”.
41 • -o, --output=FILE:
43 Optional file record of the HMAC result. Defaults to STDOUT.
45 • -t, --ticket=FILE:
47 Optional file record of the ticket result.
49 • --cphash=FILE
51 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 • ARGUMENT the command line argument specifies the file path for the
57 data to HMAC. Defaults to STDIN if not specified.
58 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 • If the argument is a file path, then the file is loaded as a restored
65 TPM transient object.
66 • If the argument is a prefix match on one of:
68 • owner: the owner hierarchy
70 • platform: the platform hierarchy
72 • endorsement: the endorsement hierarchy
74 • lockout: the lockout control persistent object
76 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
85 fied”.
86 Passwords
88 Passwords are interpreted in the following forms below using prefix
89 identifiers.
90 Note: By default passwords are assumed to be in the string form when
92 they do not have a prefix.
93 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 Examples
100 foobar
101 str:foobar
102 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 Example
109 hex:0x1122334455667788
110 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 Examples
119 # to use stdin and be prompted
120 file:-
121 # to use a file from a path
123 file:path/to/password/file
124 # to echo a password via stdin:
126 echo foobar | tpm2_tool -p file:-
127 # to use a bash here-string via stdin:
129 tpm2_tool -p file:- <<< foobar
131 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 Examples
141 To use a session context file called session.ctx.
142 session:session.ctx
144 To use a session context file called session.ctx AND send the authvalue
146 mypassword.
147 session:session.ctx+mypassword
149 To use a session context file called session.ctx AND send the HEX auth‐
151 value 0x11223344.
152 session:session.ctx+hex:11223344
154 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 The PCR spec is documented in in the section “PCR bank specifiers”.
161 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 PCR bank specifiers (pcr.md)
166 Examples
168 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
169 er of:
170 pcr:sha256:0,1,2,3
172 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
180 fied”.
181 Passwords
183 Passwords are interpreted in the following forms below using prefix
184 identifiers.
185 Note: By default passwords are assumed to be in the string form when
187 they do not have a prefix.
188 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 Examples
195 foobar
196 str:foobar
197 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 Example
204 hex:0x1122334455667788
205 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 Examples
214 # to use stdin and be prompted
215 file:-
216 # to use a file from a path
218 file:path/to/password/file
219 # to echo a password via stdin:
221 echo foobar | tpm2_tool -p file:-
222 # to use a bash here-string via stdin:
224 tpm2_tool -p file:- <<< foobar
226 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 Examples
236 To use a session context file called session.ctx.
237 session:session.ctx
239 To use a session context file called session.ctx AND send the authvalue
241 mypassword.
242 session:session.ctx+mypassword
244 To use a session context file called session.ctx AND send the HEX auth‐
246 value 0x11223344.
247 session:session.ctx+hex:11223344
249 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 The PCR spec is documented in in the section “PCR bank specifiers”.
256 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 PCR bank specifiers (pcr.md)
261 Examples
263 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
264 er of:
265 pcr:sha256:0,1,2,3
267 ALGORITHM.
269
271 This collection of options are common to many programs and provide in‐
272 formation that many users may expect.
273 • -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 To successfully use the manpages feature requires the manpages to be
283 installed or on MANPATH, See man(1) for more details.
284 • -v, --version: Display version information for this tool, supported
286 tctis and exit.
287 • -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 • -Q, --quiet: Silence normal tool output to stdout.
293 • -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 To control the TCTI, the tools respect:
305 1. The command line option -T or --tcti
307 2. The environment variable: TPM2TOOLS_TCTI.
309 Note: The command line option always overrides the environment vari‐
311 able.
312 The current known TCTIs are:
314 • 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 • mssim - Typically used for communicating to the TPM software simula‐
320 tor.
321 • device - Used when talking directly to a TPM device file.
323 • 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 The arguments to either the command line option or the environment
331 variable are in the form:
332 <tcti-name>:<tcti-option-config>
334 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
361 vice:/dev/tpm0”
362 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
368 TI=“mssim:host=localhost,port=2321”
369 • 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 • TCTI abrmd supports two keys:
375 1. `bus_name' : The name of the tabrmd service on the bus (a
377 string).
378 2. `bus_type' : The type of the dbus instance (a string) limited to
380 `session' and `system'.
381 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
383 ample.FooBar:
384 \--tcti=tabrmd:bus_name=com.example.FooBar
386 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
388 sion:
389 \--tcti:bus_type=session
391 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 # create an hmac key
401 tpm2_create -C primary.ctx -G hmac -c hmac.key
402 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 tpm2_hmac -c hmac.key --hex data.in
408 e6eda48a53a9ddbb92f788f6d98e0372d63a408afb11aca43f522a2475a32805
409
411 Tools can return any of the following codes:
412 • 0 - Success.
414 • 1 - General non-specific error.
416 • 2 - Options handling error.
418 • 3 - Authentication error.
420 • 4 - TCTI related error.
422 • 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)
430tpm2-tools tpm2_hmac(1)