1tpm2_getcommandauditdigest(1)General Commands Manuatlpm2_getcommandauditdigest(1)
2
3
4
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
23 Specifies the authorization value for the endorsement hierarchy.
24
25 • -c, --key-context=OBJECT:
26
27 Context object for the signing key that signs the attestation data.
28
29 • -p, --auth=AUTH:
30
31 Specifies the authorization value for key specified by option -c.
32
33 • -q, --qualification=HEX_STRING_OR_PATH:
34
35 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
39 • -s, --signature=FILE:
40
41 Signature output file, records the signature in the format specified
42 via the -f option.
43
44 • -m, --message=FILE:
45
46 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
50 • -f, --format=FORMAT:
51
52 Format selection for the signature output file.
53
54 • -g, --hash-algorithm:
55
56 Hash algorithm for signature. Defaults to sha256.
57
58 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
63 • If the argument is a file path, then the file is loaded as a restored
64 TPM transient object.
65
66 • If the argument is a prefix match on one of:
67
68 • owner: the owner hierarchy
69
70 • platform: the platform hierarchy
71
72 • endorsement: the endorsement hierarchy
73
74 • lockout: the lockout control persistent object
75
76 • 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
83 NOTE: "Authorizations default to the EMPTY PASSWORD when not speci‐
84 fied".
85
86 Passwords
87 Passwords are interpreted in the following forms below using prefix
88 identifiers.
89
90 Note: By default passwords are assumed to be in the string form when
91 they do not have a prefix.
92
93 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
98 Examples
99 foobar
100 str:foobar
101
102 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
107 Example
108 hex:0x1122334455667788
109
110 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
117 Examples
118 # to use stdin and be prompted
119 file:-
120
121 # to use a file from a path
122 file:path/to/password/file
123
124 # to echo a password via stdin:
125 echo foobar | tpm2_tool -p file:-
126
127 # to use a bash here-string via stdin:
128
129 tpm2_tool -p file:- <<< foobar
130
131 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
139 Examples
140 To use a session context file called session.ctx.
141
142 session:session.ctx
143
144 To use a session context file called session.ctx AND send the authvalue
145 mypassword.
146
147 session:session.ctx+mypassword
148
149 To use a session context file called session.ctx AND send the HEX auth‐
150 value 0x11223344.
151
152 session:session.ctx+hex:11223344
153
154 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
159 The PCR spec is documented in in the section "PCR bank specifiers".
160
161 The raw-pcr-file is an optional the output of the raw PCR contents as
162 returned by tpm2_pcrread(1).
163
164 PCR bank specifiers (common/pcr.md)
165
166 Examples
167 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
168 er of:
169
170 pcr:sha256:0,1,2,3
171
172 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
185 • -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
193 To successfully use the manpages feature requires the manpages to be
194 installed or on MANPATH, See man(1) for more details.
195
196 • -v, --version: Display version information for this tool, supported
197 tctis and exit.
198
199 • -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
203 • -Q, --quiet: Silence normal tool output to stdout.
204
205 • -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
215 To control the TCTI, the tools respect:
216
217 1. The command line option -T or --tcti
218
219 2. The environment variable: TPM2TOOLS_TCTI.
220
221 Note: The command line option always overrides the environment vari‐
222 able.
223
224 The current known TCTIs are:
225
226 • 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
230 • mssim - Typically used for communicating to the TPM software simula‐
231 tor.
232
233 • device - Used when talking directly to a TPM device file.
234
235 • 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
241 The arguments to either the command line option or the environment
242 variable are in the form:
243
244 <tcti-name>:<tcti-option-config>
245
246 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
250 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
258 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
268 • 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
271 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
272 vice:/dev/tpm0"
273
274 • 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
278 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
279 TI="mssim:host=localhost,port=2321"
280
281 • 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
285 • TCTI abrmd supports two keys:
286
287 1. 'bus_name' : The name of the tabrmd service on the bus (a
288 string).
289
290 2. 'bus_type' : The type of the dbus instance (a string) limited to
291 'session' and 'system'.
292
293 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
294 ample.FooBar:
295
296 \--tcti=tabrmd:bus_name=com.example.FooBar
297
298 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
299 sion:
300
301 \--tcti:bus_type=session
302
303 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
312 • 0 - Success.
313
314 • 1 - General non-specific error.
315
316 • 2 - Options handling error.
317
318 • 3 - Authentication error.
319
320 • 4 - TCTI related error.
321
322 • 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)
329
330
331
332tpm2-tools tpm2_getcommandauditdigest(1)