1tpm2_getcommandauditdigest(1)General Commands Manuatlpm2_getcommandauditdigest(1)
2
3
4

NAME

6       tpm2_getcommandauditdigest(1)  - Retrieve the command audit attestation
7       data from the TPM.
8

SYNOPSIS

10       tpm2_getcommandauditdigest [OPTIONS]
11

DESCRIPTION

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

OPTIONS

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

Context Object Format

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

Authorization Formatting

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

Signature Format Specifiers

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

265       This collection of options are used to configure the various known TCTI
266       modules available:
267
268device: 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

EXAMPLES

307              tpm2_getcommandauditdigest -P ekpass -c key.ctx -p keypass -m att.data -s att.sig
308

Returns

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

BUGS

325       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
326

HELP

328       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
329
330
331
332tpm2-tools                                       tpm2_getcommandauditdigest(1)
Impressum