1tpm2_getcommandauditdigest(1)General Commands Manuatlpm2_getcommandauditdigest(1)
2
6 tpm2_getcommandauditdigest(1) - Retrieve the command audit attestation
7 data from the TPM.
8
10 tpm2_getcommandauditdigest [OPTIONS]
11
13 tpm2_getcommandauditdigest(1) - Retrieve the command audit attestation
14 data from the TPM. The attestation data includes the audit digest of
15 the commands in the setlist setup using the command tpm2_setcommandau‐
16 ditstatus. Also the attestation data includes the digest of the list
17 of commands setup for audit. The audit digest algorith is setup in the
18 tpm2_setcommandauditstatus.
19
21 • -P, --hierarchy-auth=AUTH:
22 Specifies the authorization value for the endorsement hierarchy.
24 • -c, --key-context=OBJECT:
26 Context object for the signing key that signs the attestation data.
28 • -p, --auth=AUTH:
30 Specifies the authorization value for key specified by option -c.
32 • -q, --qualification=HEX_STRING_OR_PATH:
34 Data given as a Hex string or binary file to qualify the quote, op‐
36 tional. This is typically used to add a nonce against replay at‐
37 tacks.
38 • -s, --signature=FILE:
40 Signature output file, records the signature in the format specified
42 via the -f option.
43 • -m, --message=FILE:
45 Message output file, records the quote message that makes up the data
47 that is signed by the TPM. This is the command audit digest attesta‐
48 tion data.
49 • -f, --format=FORMAT:
51 Format selection for the signature output file.
53 • -g, --hash-algorithm:
55 Hash algorithm for signature. Defaults to sha256.
57 References
60 The type of a context object, whether it is a handle or file name, is
61 determined according to the following logic in-order:
62 • If the argument is a file path, then the file is loaded as a restored
64 TPM transient object.
65 • If the argument is a prefix match on one of:
67 • owner: the owner hierarchy
69 • platform: the platform hierarchy
71 • endorsement: the endorsement hierarchy
73 • lockout: the lockout control persistent object
75 • If the argument argument can be loaded as a number it will be treat
77 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
78
80 Authorization for use of an object in TPM2.0 can come in 3 different
81 forms: 1. Password 2. HMAC 3. Sessions
82 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
84 fied”.
85 Passwords
87 Passwords are interpreted in the following forms below using prefix
88 identifiers.
89 Note: By default passwords are assumed to be in the string form when
91 they do not have a prefix.
92 String
94 A string password, specified by prefix “str:” or it’s absence (raw
95 string without prefix) is not interpreted, and is directly used for au‐
96 thorization.
97 Examples
99 foobar
100 str:foobar
101 Hex-string
103 A hex-string password, specified by prefix “hex:” is converted from a
104 hexidecimal form into a byte array form, thus allowing passwords with
105 non-printable and/or terminal un-friendly characters.
106 Example
108 hex:0x1122334455667788
109 File
111 A file based password, specified be prefix “file:” should be the path
112 of a file containing the password to be read by the tool or a “-” to
113 use stdin. Storing passwords in files prevents information leakage,
114 passwords passed as options can be read from the process list or common
115 shell history features.
116 Examples
118 # to use stdin and be prompted
119 file:-
120 # to use a file from a path
122 file:path/to/password/file
123 # to echo a password via stdin:
125 echo foobar | tpm2_tool -p file:-
126 # to use a bash here-string via stdin:
128 tpm2_tool -p file:- <<< foobar
130 Sessions
132 When using a policy session to authorize the use of an object, prefix
133 the option argument with the session keyword. Then indicate a path to
134 a session file that was created with tpm2_startauthsession(1). Option‐
135 ally, if the session requires an auth value to be sent with the session
136 handle (eg policy password), then append a + and a string as described
137 in the Passwords section.
138 Examples
140 To use a session context file called session.ctx.
141 session:session.ctx
143 To use a session context file called session.ctx AND send the authvalue
145 mypassword.
146 session:session.ctx+mypassword
148 To use a session context file called session.ctx AND send the HEX auth‐
150 value 0x11223344.
151 session:session.ctx+hex:11223344
153 PCR Authorizations
155 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
156 language. The PCR minilanguage is as follows:
157 <pcr-spec>=<raw-pcr-file>
158 The PCR spec is documented in in the section “PCR bank specifiers”.
160 The raw-pcr-file is an optional argument that contains the output of
162 the raw PCR contents as returned by tpm2_pcrread(1).
163 PCR bank specifiers (pcr.md)
165 Examples
167 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
168 er of:
169 pcr:sha256:0,1,2,3
171 specifying AUTH.
173
175 Format selection for the signature output file. tss (the default) will
176 output a binary blob according to the TPM 2.0 specification and any po‐
177 tential compiler padding. The option plain will output the plain sig‐
178 nature data as defined by the used cryptographic algorithm. signature
179 FORMAT.
180
182 This collection of options are common to many programs and provide in‐
183 formation that many users may expect.
184 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
186 attempts to invoke the manpager for the tool, however, on failure
187 will output a short tool summary. This is the same behavior if the
188 “man” option argument is specified, however if explicit “man” is re‐
189 quested, the tool will provide errors from man on stderr. If the
190 “no-man” option if specified, or the manpager fails, the short op‐
191 tions will be output to stdout.
192 To successfully use the manpages feature requires the manpages to be
194 installed or on MANPATH, See man(1) for more details.
195 • -v, --version: Display version information for this tool, supported
197 tctis and exit.
198 • -V, --verbose: Increase the information that the tool prints to the
200 console during its execution. When using this option the file and
201 line number are printed.
202 • -Q, --quiet: Silence normal tool output to stdout.
204 • -Z, --enable-errata: Enable the application of errata fixups. Useful
206 if an errata fixup needs to be applied to commands sent to the TPM.
207 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
208 formation many users may expect.
209
211 The TCTI or “Transmission Interface” is the communication mechanism
212 with the TPM. TCTIs can be changed for communication with TPMs across
213 different mediums.
214 To control the TCTI, the tools respect:
216 1. The command line option -T or --tcti
218 2. The environment variable: TPM2TOOLS_TCTI.
220 Note: The command line option always overrides the environment vari‐
222 able.
223 The current known TCTIs are:
225 • tabrmd - The resource manager, called tabrmd
227 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
228 abrmd as a tcti name are synonymous.
229 • mssim - Typically used for communicating to the TPM software simula‐
231 tor.
232 • device - Used when talking directly to a TPM device file.
234 • none - Do not initalize a connection with the TPM. Some tools allow
236 for off-tpm options and thus support not using a TCTI. Tools that do
237 not support it will error when attempted to be used without a TCTI
238 connection. Does not support ANY options and MUST BE presented as
239 the exact text of “none”.
240 The arguments to either the command line option or the environment
242 variable are in the form:
243 <tcti-name>:<tcti-option-config>
245 Specifying an empty string for either the <tcti-name> or <tcti-op‐
247 tion-config> results in the default being used for that portion respec‐
248 tively.
249 TCTI Defaults
251 When a TCTI is not specified, the default TCTI is searched for using
252 dlopen(3) semantics. The tools will search for tabrmd, device and
253 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
254 what TCTI will be chosen as the default by using the -v option to print
255 the version information. The “default-tcti” key-value pair will indi‐
256 cate which of the aforementioned TCTIs is the default.
257 Custom TCTIs
259 Any TCTI that implements the dynamic TCTI interface can be loaded. The
260 tools internally use dlopen(3), and the raw tcti-name value is used for
261 the lookup. Thus, this could be a path to the shared library, or a li‐
262 brary name as understood by dlopen(3) semantics.
263
265 This collection of options are used to configure the various known TCTI
266 modules available:
267 • device: For the device TCTI, the TPM character device file for use by
269 the device TCTI can be specified. The default is /dev/tpm0.
270 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
272 vice:/dev/tpm0”
273 • mssim: For the mssim TCTI, the domain name or IP address and port
275 number used by the simulator can be specified. The default are
276 127.0.0.1 and 2321.
277 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
279 TI=“mssim:host=localhost,port=2321”
280 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
282 ries of simple key value pairs separated by a `,' character. Each
283 key and value string are separated by a `=' character.
284 • TCTI abrmd supports two keys:
286 1. `bus_name' : The name of the tabrmd service on the bus (a
288 string).
289 2. `bus_type' : The type of the dbus instance (a string) limited to
291 `session' and `system'.
292 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
294 ample.FooBar:
295 \--tcti=tabrmd:bus_name=com.example.FooBar
297 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
299 sion:
300 \--tcti:bus_type=session
302 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
304 ules.
305
307 tpm2_getcommandauditdigest -P ekpass -c key.ctx -p keypass -m att.data -s att.sig
308
310 Tools can return any of the following codes:
311 • 0 - Success.
313 • 1 - General non-specific error.
315 • 2 - Options handling error.
317 • 3 - Authentication error.
319 • 4 - TCTI related error.
321 • 5 - Non supported scheme. Applicable to tpm2_testparams.
323
325 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
326
328 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
329tpm2-tools tpm2_getcommandauditdigest(1)