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

NAME

6       tpm2_hmac(1) - Performs an HMAC operation with the TPM.
7

SYNOPSIS

9       tpm2_hmac [OPTIONS] [ARGUMENT]
10

DESCRIPTION

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

OPTIONS

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
56ARGUMENT the command line argument specifies the file  path  for  the
57         data to HMAC.  Defaults to STDIN if not specified.
58
59   References

Context Object Format

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

Authorization Formatting

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 the output of the raw PCR contents as
163       returned by tpm2_pcrread(1).
164
165       PCR bank specifiers (common/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

Authorization Formatting

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 the output of the raw PCR  contents  as
258       returned by tpm2_pcrread(1).
259
260       PCR bank specifiers (common/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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

354       This collection of options are used to configure the various known TCTI
355       modules available:
356
357device: 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

EXAMPLES

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

Returns

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

BUGS

426       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
427

HELP

429       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
430
431
432
433tpm2-tools                                                        tpm2_hmac(1)
Impressum