1tpm2_hash(1) General Commands Manual tpm2_hash(1)
2
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 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 • o for TPM_RH_OWNER
27 • p for TPM_RH_PLATFORM
29 • e for TPM_RH_ENDORSEMENT
31 • n for TPM_RH_NULL
33 • -g, --hash-algorithm=ALGORITHM:
35 The hashing algorithm for the digest operation.
37 • --hex
39 Convert the output hmac to hex format without a leading “0x”.
41 • -o, --output=FILE or STDOUT:
43 Optional file to save the hash result. Defaults to stdout in hex
45 form.
46 • -t, --ticket=TICKET_FILE
48 Optional file record of the ticket result. Defaults to stdout in hex
50 form.
51 • ARGUMENT or STDIN the command line argument specifies the FILE to
53 hash.
54 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 • If the argument is a file path, then the file is loaded as a restored
61 TPM transient object.
62 • If the argument is a prefix match on one of:
64 • owner: the owner hierarchy
66 • platform: the platform hierarchy
68 • endorsement: the endorsement hierarchy
70 • lockout: the lockout control persistent object
72 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
81 fied”.
82 Passwords
84 Passwords are interpreted in the following forms below using prefix
85 identifiers.
86 Note: By default passwords are assumed to be in the string form when
88 they do not have a prefix.
89 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 Examples
96 foobar
97 str:foobar
98 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 Example
105 hex:1122334455667788
106 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 Examples
115 # to use stdin and be prompted
116 file:-
117 # to use a file from a path
119 file:path/to/password/file
120 # to echo a password via stdin:
122 echo foobar | tpm2_tool -p file:-
123 # to use a bash here-string via stdin:
125 tpm2_tool -p file:- <<< foobar
127 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 Examples
137 To use a session context file called session.ctx.
138 session:session.ctx
140 To use a session context file called session.ctx AND send the authvalue
142 mypassword.
143 session:session.ctx+mypassword
145 To use a session context file called session.ctx AND send the HEX auth‐
147 value 0x11223344.
148 session:session.ctx+hex:11223344
150 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 The PCR spec is documented in in the section “PCR bank specifiers”.
157 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 PCR bank specifiers (pcr.md)
162 Examples
164 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
165 er of:
166 pcr:sha256:0,1,2,3
168 ALGORITHM.
170
172 This collection of options are common to many programs and provide in‐
173 formation that many users may expect.
174 • -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 To successfully use the manpages feature requires the manpages to be
184 installed or on MANPATH, See man(1) for more details.
185 • -v, --version: Display version information for this tool, supported
187 tctis and exit.
188 • -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 • -Q, --quiet: Silence normal tool output to stdout.
194 • -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 To control the TCTI, the tools respect:
206 1. The command line option -T or --tcti
208 2. The environment variable: TPM2TOOLS_TCTI.
210 Note: The command line option always overrides the environment vari‐
212 able.
213 The current known TCTIs are:
215 • 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 • mssim - Typically used for communicating to the TPM software simula‐
221 tor.
222 • device - Used when talking directly to a TPM device file.
224 • 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 The arguments to either the command line option or the environment
232 variable are in the form:
233 <tcti-name>:<tcti-option-config>
235 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
262 vice:/dev/tpm0”
263 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
269 TI=“mssim:host=localhost,port=2321”
270 • 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 • TCTI abrmd supports two keys:
276 1. `bus_name' : The name of the tabrmd service on the bus (a
278 string).
279 2. `bus_type' : The type of the dbus instance (a string) limited to
281 `session' and `system'.
282 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
284 ample.FooBar:
285 \--tcti=tabrmd:bus_name=com.example.FooBar
287 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
289 sion:
290 \--tcti:bus_type=session
292 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 a file
298 tpm2_hash -C e -g sha1 -o hash.bin -t ticket.bin data.txt
299
301 Tools can return any of the following codes:
302 • 0 - Success.
304 • 1 - General non-specific error.
306 • 2 - Options handling error.
308 • 3 - Authentication error.
310 • 4 - TCTI related error.
312 • 5 - Non supported scheme. Applicable to tpm2_testparams.
314
316 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
317
319 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
320 fo/tpm2)
321tpm2-tools tpm2_hash(1)