1tpm2_print(1) General Commands Manual tpm2_print(1)
2
6 tpm2_print(1) - Prints TPM data structures
7
9 tpm2_print [OPTIONS] [ARGUMENT or STDIN]
10
12 tpm2_print(1) - Decodes a TPM data structure and prints enclosed ele‐
13 ments to stdout as YAML. A file path containing a TPM object may be
14 specified as the path argument. Reads from stdin if unspecified.
15
17 · -t, --type:
18 Required. Type of data structure. Only TPMS_ATTEST and TPMS_CONTEXT
20 are presently supported.
21 · ARGUMENT the command line argument specifies the path of the TPM da‐
23 ta.
24 References
27 The type of a context object, whether it is a handle or file name, is
28 determined according to the following logic in-order:
29 · If the argument is a file path, then the file is loaded as a restored
31 TPM transient object.
32 · If the argument is a prefix match on one of:
34 · owner: the owner hierarchy
36 · platform: the platform hierarchy
38 · endorsement: the endorsement hierarchy
40 · lockout: the lockout control persistent object
42 · If the argument argument can be loaded as a number it will be treat
44 as a handle, e.g. 0x81010013 and used directly.OBJECT.
45
47 Authorization for use of an object in TPM2.0 can come in 3 different
48 forms: 1. Password 2. HMAC 3. Sessions
49 NOTE: "Authorizations default to the EMPTY PASSWORD when not speci‐
51 fied".
52 Passwords
54 Passwords are interpreted in the following forms below using prefix
55 identifiers.
56 Note: By default passwords are assumed to be in the string form when
58 they do not have a prefix.
59 String
61 A string password, specified by prefix "str:" or it's absence (raw
62 string without prefix) is not interpreted, and is directly used for au‐
63 thorization.
64 Examples
66 foobar
67 str:foobar
68 Hex-string
70 A hex-string password, specified by prefix "hex:" is converted from a
71 hexidecimal form into a byte array form, thus allowing passwords with
72 non-printable and/or terminal un-friendly characters.
73 Example
75 hex:0x1122334455667788
76 File
78 A file based password, specified be prefix "file:" should be the path
79 of a file containing the password to be read by the tool or a "-" to
80 use stdin. Storing passwords in files prevents information leakage,
81 passwords passed as options can be read from the process list or common
82 shell history features.
83 Examples
85 # to use stdin and be prompted
86 file:-
87 # to use a file from a path
89 file:path/to/password/file
90 # to echo a password via stdin:
92 echo foobar | tpm2_tool -p file:-
93 # to use a bash here-string via stdin:
95 tpm2_tool -p file:- <<< foobar
97 Sessions
99 When using a policy session to authorize the use of an object, prefix
100 the option argument with the session keyword. Then indicate a path to
101 a session file that was created with tpm2_startauthsession(1). Option‐
102 ally, if the session requires an auth value to be sent with the session
103 handle (eg policy password), then append a + and a string as described
104 in the Passwords section.
105 Examples
107 To use a session context file called session.ctx.
108 session:session.ctx
110 To use a session context file called session.ctx AND send the authvalue
112 mypassword.
113 session:session.ctx+mypassword
115 To use a session context file called session.ctx AND send the HEX auth‐
117 value 0x11223344.
118 session:session.ctx+hex:11223344
120 PCR Authorizations
122 You can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
123 language. The PCR minilanguage is as follows:
124 <pcr-spec>=<raw-pcr-file>
125 The PCR spec is documented in in the section "PCR bank specifiers".
127 The raw-pcr-file is an optional the output of the raw PCR contents as
129 returned by tpm2_pcrread(1).
130 PCR bank specifiers (common/pcr.md)
132 Examples
134 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
135 er of:
136 pcr:sha256:0,1,2,3
138 specifying AUTH.
140
142 This collection of options are common to many programs and provide in‐
143 formation that many users may expect.
144 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
146 attempts to invoke the manpager for the tool, however, on failure
147 will output a short tool summary. This is the same behavior if the
148 "man" option argument is specified, however if explicit "man" is re‐
149 quested, the tool will provide errors from man on stderr. If the
150 "no-man" option if specified, or the manpager fails, the short op‐
151 tions will be output to stdout.
152 To successfully use the manpages feature requires the manpages to be
154 installed or on MANPATH, See man(1) for more details.
155 · -v, --version: Display version information for this tool, supported
157 tctis and exit.
158 · -V, --verbose: Increase the information that the tool prints to the
160 console during its execution. When using this option the file and
161 line number are printed.
162 · -Q, --quiet: Silence normal tool output to stdout.
164 · -Z, --enable-errata: Enable the application of errata fixups. Useful
166 if an errata fixup needs to be applied to commands sent to the TPM.
167 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
168 formation many users may expect.
169
171 The TCTI or "Transmission Interface" is the communication mechanism
172 with the TPM. TCTIs can be changed for communication with TPMs across
173 different mediums.
174 To control the TCTI, the tools respect:
176 1. The command line option -T or --tcti
178 2. The environment variable: TPM2TOOLS_TCTI.
180 Note: The command line option always overrides the environment vari‐
182 able.
183 The current known TCTIs are:
185 · tabrmd - The resource manager, called tabrmd
187 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
188 abrmd as a tcti name are synonymous.
189 · mssim - Typically used for communicating to the TPM software simula‐
191 tor.
192 · device - Used when talking directly to a TPM device file.
194 · none - Do not initalize a connection with the TPM. Some tools allow
196 for off-tpm options and thus support not using a TCTI. Tools that do
197 not support it will error when attempted to be used without a TCTI
198 connection. Does not support ANY options and MUST BE presented as
199 the exact text of "none".
200 The arguments to either the command line option or the environment
202 variable are in the form:
203 <tcti-name>:<tcti-option-config>
205 Specifying an empty string for either the <tcti-name> or <tcti-op‐
207 tion-config> results in the default being used for that portion respec‐
208 tively.
209 TCTI Defaults
211 When a TCTI is not specified, the default TCTI is searched for using
212 dlopen(3) semantics. The tools will search for tabrmd, device and
213 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
214 what TCTI will be chosen as the default by using the -v option to print
215 the version information. The "default-tcti" key-value pair will indi‐
216 cate which of the aforementioned TCTIs is the default.
217 Custom TCTIs
219 Any TCTI that implements the dynamic TCTI interface can be loaded. The
220 tools internally use dlopen(3), and the raw tcti-name value is used for
221 the lookup. Thus, this could be a path to the shared library, or a li‐
222 brary name as understood by dlopen(3) semantics.
223
225 This collection of options are used to configure the various known TCTI
226 modules available:
227 · device: For the device TCTI, the TPM character device file for use by
229 the device TCTI can be specified. The default is /dev/tpm0.
230 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
232 vice:/dev/tpm0"
233 · mssim: For the mssim TCTI, the domain name or IP address and port
235 number used by the simulator can be specified. The default are
236 127.0.0.1 and 2321.
237 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
239 TI="mssim:host=localhost,port=2321"
240 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
242 ries of simple key value pairs separated by a ',' character. Each
243 key and value string are separated by a '=' character.
244 · TCTI abrmd supports two keys:
246 1. 'bus_name' : The name of the tabrmd service on the bus (a
248 string).
249 2. 'bus_type' : The type of the dbus instance (a string) limited to
251 'session' and 'system'.
252 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
254 ample.FooBar:
255 \--tcti=tabrmd:bus_name=com.example.FooBar
257 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
259 sion:
260 \--tcti:bus_type=session
262 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
264 ules.
265 References
268 This collection of options are common to many programs and provide in‐
269 formation that many users may expect.
270 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
272 attempts to invoke the manpager for the tool, however, on failure
273 will output a short tool summary. This is the same behavior if the
274 "man" option argument is specified, however if explicit "man" is re‐
275 quested, the tool will provide errors from man on stderr. If the
276 "no-man" option if specified, or the manpager fails, the short op‐
277 tions will be output to stdout.
278 To successfully use the manpages feature requires the manpages to be
280 installed or on MANPATH, See man(1) for more details.
281 · -v, --version: Display version information for this tool, supported
283 tctis and exit.
284 · -V, --verbose: Increase the information that the tool prints to the
286 console during its execution. When using this option the file and
287 line number are printed.
288 · -Q, --quiet: Silence normal tool output to stdout.
290 · -Z, --enable-errata: Enable the application of errata fixups. Useful
292 if an errata fixup needs to be applied to commands sent to the TPM.
293 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
294 formation many users may expect.
295
297 The TCTI or "Transmission Interface" is the communication mechanism
298 with the TPM. TCTIs can be changed for communication with TPMs across
299 different mediums.
300 To control the TCTI, the tools respect:
302 1. The command line option -T or --tcti
304 2. The environment variable: TPM2TOOLS_TCTI.
306 Note: The command line option always overrides the environment vari‐
308 able.
309 The current known TCTIs are:
311 · tabrmd - The resource manager, called tabrmd
313 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
314 abrmd as a tcti name are synonymous.
315 · mssim - Typically used for communicating to the TPM software simula‐
317 tor.
318 · device - Used when talking directly to a TPM device file.
320 · none - Do not initalize a connection with the TPM. Some tools allow
322 for off-tpm options and thus support not using a TCTI. Tools that do
323 not support it will error when attempted to be used without a TCTI
324 connection. Does not support ANY options and MUST BE presented as
325 the exact text of "none".
326 The arguments to either the command line option or the environment
328 variable are in the form:
329 <tcti-name>:<tcti-option-config>
331 Specifying an empty string for either the <tcti-name> or <tcti-op‐
333 tion-config> results in the default being used for that portion respec‐
334 tively.
335 TCTI Defaults
337 When a TCTI is not specified, the default TCTI is searched for using
338 dlopen(3) semantics. The tools will search for tabrmd, device and
339 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
340 what TCTI will be chosen as the default by using the -v option to print
341 the version information. The "default-tcti" key-value pair will indi‐
342 cate which of the aforementioned TCTIs is the default.
343 Custom TCTIs
345 Any TCTI that implements the dynamic TCTI interface can be loaded. The
346 tools internally use dlopen(3), and the raw tcti-name value is used for
347 the lookup. Thus, this could be a path to the shared library, or a li‐
348 brary name as understood by dlopen(3) semantics.
349
351 This collection of options are used to configure the various known TCTI
352 modules available:
353 · device: For the device TCTI, the TPM character device file for use by
355 the device TCTI can be specified. The default is /dev/tpm0.
356 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
358 vice:/dev/tpm0"
359 · mssim: For the mssim TCTI, the domain name or IP address and port
361 number used by the simulator can be specified. The default are
362 127.0.0.1 and 2321.
363 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
365 TI="mssim:host=localhost,port=2321"
366 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
368 ries of simple key value pairs separated by a ',' character. Each
369 key and value string are separated by a '=' character.
370 · TCTI abrmd supports two keys:
372 1. 'bus_name' : The name of the tabrmd service on the bus (a
374 string).
375 2. 'bus_type' : The type of the dbus instance (a string) limited to
377 'session' and 'system'.
378 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
380 ample.FooBar:
381 \--tcti=tabrmd:bus_name=com.example.FooBar
383 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
385 sion:
386 \--tcti:bus_type=session
388 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
390 ules.
391
393 Print a TPM Quote
394 Setup a key to generate a qoute from
395 tpm2_createprimary -C e -c primary.ctx
396 tpm2_create -C primary.ctx -u key.pub -r key.priv
397 tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
398 tpm2_quote -c key.ctx -l 0x0004:16,17,18+0x000b:16,17,18 -g sha256 -m msg.dat
399 Print a Quote
401 tpm2_print -t TPMS_ATTEST msg.dat
402
404 Tools can return any of the following codes:
405 · 0 - Success.
407 · 1 - General non-specific error.
409 · 2 - Options handling error.
411 · 3 - Authentication error.
413 · 4 - TCTI related error.
415 · 5 - Non supported scheme. Applicable to tpm2_testparams.
417
419 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
420
422 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
423tpm2-tools tpm2_print(1)