1tpm2_checkquote(1)          General Commands Manual         tpm2_checkquote(1)
2
3
4

NAME

6       tpm2_checkquote(1) - Validates a quote provided by a TPM.
7

SYNOPSIS

9       tpm2_checkquote [OPTIONS]
10

DESCRIPTION

12       tpm2_checkquote(1)  -  Uses  the  public portion of the provided key to
13       validate a quote generated by a TPM.  This will validate the  signature
14       against  the quote message and, if provided, verify that the qualifying
15       data and PCR values match those in the quote.
16

OPTIONS

18       · -u, --public=FILE:
19
20         File input for the public portion of the signature verification key.
21
22       · -g, --hash-algorithm=ALGORITHM:
23
24         The hash algorithm used to digest the message.
25
26       · -m, --message=FILE:
27
28         The quote message that makes up the data that is signed by the TPM.
29
30       · -s, --signature=FILE:
31
32         The input signature file of the signature to be validated.
33
34       · -F, --format=FORMAT:
35
36         Signature format.  The default is the TPM2.0  TPMT_SIGNATURE.   Other
37         schemes  are  possible  if the data came from an external source like
38         OpenSSL.  The tool currently only supports rsassa.
39
40       · -f, --pcr=FILE:
41
42         Optional PCR input file to save the list of PCR values that were  in‐
43         cluded in the quote.
44
45       · -q, --qualification=HEX_STRING:
46
47         Qualification  data  for  the quote.  This is typically used to add a
48         nonce against replay attacks.
49
50   References

Algorithm Specifiers

52       Options that take algorithms support "nice-names".
53
54       There are two major algorithm specification string classes, simple  and
55       complex.  Only certain algorithms will be accepted by the TPM, based on
56       usage and conditions.
57
58   Simple specifiers
59       These are strings with no additional specification data.  When creating
60       objects,  non-specified  portions of an object are assumed to defaults.
61       You can find the list of known "Simple Specifiers Below".
62
63   Asymmetric
64       · rsa
65
66       · ecc
67
68   Symmetric
69       · aes
70
71       · camellia
72
73   Hashing Algorithms
74       · sha1
75
76       · sha256
77
78       · sha384
79
80       · sha512
81
82       · sm3_256
83
84       · sha3_256
85
86       · sha3_384
87
88       · sha3_512
89
90   Keyed Hash
91       · hmac
92
93       · xor
94
95   Signing Schemes
96       · rsassa
97
98       · rsapss
99
100       · ecdsa
101
102       · ecdaa
103
104       · ecschnorr
105
106   Asymmetric Encryption Schemes
107       · oaep
108
109       · rsaes
110
111       · ecdh
112
113   Modes
114       · ctr
115
116       · ofb
117
118       · cbc
119
120       · cfb
121
122       · ecb
123
124   Misc
125       · null
126
127   Complex Specifiers
128       Objects, when specified for creation by the TPM,  have  numerous  algo‐
129       rithms  to  populate  in the public data.  Things like type, scheme and
130       asymmetric details, key size, etc.  Below is  the  general  format  for
131       specifying this data: <type>:<scheme>:<symmetric-details>
132
133   Type Specifiers
134       This  portion  of the complex algorithm specifier is required.  The re‐
135       maining scheme and symmetric details will default  based  on  the  type
136       specified and the type of the object being created.
137
138       · aes - Default AES: aes128
139
140       · aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
141         If mode is not specified, defaults to null.
142
143       · aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
144
145       · aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
146
147       · ecc - Elliptical Curve, defaults to ecc256.
148
149       · ecc192 - 192 bit ECC
150
151       · ecc224 - 224 bit ECC
152
153       · ecc256 - 256 bit ECC
154
155       · ecc384 - 384 bit ECC
156
157       · ecc521 - 521 bit ECC
158
159       · rsa - Default RSA: rsa2048
160
161       · rsa1024 - RSA with 1024 bit keysize.
162
163       · rsa2048 - RSA with 2048 bit keysize.
164
165       · rsa4096 - RSA with 4096 bit keysize.
166
167   Scheme Specifiers
168       Next, is an optional field, it can be skipped.
169
170       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
171       Most signing schemes take a hash algorithm directly following the sign‐
172       ing scheme.  If the hash algorithm is missing, it defaults  to  sha256.
173       Some take no arguments, and some take multiple arguments.
174
175   Hash Optional Scheme Specifiers
176       These  scheme  specifiers are followed by a dash and a valid hash algo‐
177       rithm, For example: oaep-sha256.
178
179       · oaep
180
181       · ecdh
182
183       · rsassa
184
185       · rsapss
186
187       · ecdsa
188
189       · ecschnorr
190
191   Multiple Option Scheme Specifiers
192       This scheme specifier is followed by a count  (max  size  UINT16)  then
193       folloed  by a dash(-) and a valid hash algorithm.  * ecdaa For example,
194       ecdaa4-sha256.  If no count is specified, it defaults to 4.
195
196   No Option Scheme Specifiers
197       This scheme specifier takes NO arguments.  * rsaes
198
199   Symmetric Details Specifiers
200       This field is optional, and defaults based on the type of object  being
201       created  and it's attributes.  Generally, any valid Symmetric specifier
202       from the Type Specifiers list should work.  If not specified, an  asym‐
203       metric objects symmetric details defaults to aes128cfb.
204
205   Examples
206   Create an rsa2048 key with an rsaes asymmetric encryption scheme
207       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
208
209   Create an ecc256 key with an ecdaa signing scheme with a count of 4
210       and sha384 hash
211
212       /tpm2_create -C parent.ctx -G ecc256:ec‐
213       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
214

Signature Format Specifiers

216       Format selection for the signature output file.  tss (the default) will
217       output a binary blob according to the TPM 2.0 specification and any po‐
218       tential compiler padding.  The option plain will output the plain  sig‐
219       nature  data as defined by the used cryptographic algorithm.  signature
220       FORMAT.
221

COMMON OPTIONS

223       This collection of options are common to many programs and provide  in‐
224       formation that many users may expect.
225
226       · -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
227         attempts to invoke the manpager for the  tool,  however,  on  failure
228         will  output  a short tool summary.  This is the same behavior if the
229         "man" option argument is specified, however if explicit "man" is  re‐
230         quested,  the  tool  will  provide errors from man on stderr.  If the
231         "no-man" option if specified, or the manpager fails,  the  short  op‐
232         tions will be output to stdout.
233
234         To  successfully use the manpages feature requires the manpages to be
235         installed or on MANPATH, See man(1) for more details.
236
237       · -v, --version: Display version information for this  tool,  supported
238         tctis and exit.
239
240       · -V,  --verbose:  Increase the information that the tool prints to the
241         console during its execution.  When using this option  the  file  and
242         line number are printed.
243
244       · -Q, --quiet: Silence normal tool output to stdout.
245
246       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
247         if an errata fixup needs to be applied to commands sent to  the  TPM.
248         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
249         formation many users may expect.
250

TCTI Configuration

252       The TCTI or "Transmission Interface"  is  the  communication  mechanism
253       with  the TPM.  TCTIs can be changed for communication with TPMs across
254       different mediums.
255
256       To control the TCTI, the tools respect:
257
258       1. The command line option -T or --tcti
259
260       2. The environment variable: TPM2TOOLS_TCTI.
261
262       Note: The command line option always overrides  the  environment  vari‐
263       able.
264
265       The current known TCTIs are:
266
267       · tabrmd      -     The     resource     manager,     called     tabrmd
268         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
269         abrmd as a tcti name are synonymous.
270
271       · mssim  - Typically used for communicating to the TPM software simula‐
272         tor.
273
274       · device - Used when talking directly to a TPM device file.
275
276       · none - Do not initalize a connection with the TPM.  Some tools  allow
277         for off-tpm options and thus support not using a TCTI.  Tools that do
278         not support it will error when attempted to be used  without  a  TCTI
279         connection.   Does  not  support ANY options and MUST BE presented as
280         the exact text of "none".
281
282       The arguments to either the command  line  option  or  the  environment
283       variable are in the form:
284
285       <tcti-name>:<tcti-option-config>
286
287       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
288       tion-config> results in the default being used for that portion respec‐
289       tively.
290
291   TCTI Defaults
292       When  a  TCTI  is not specified, the default TCTI is searched for using
293       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
294       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
295       what TCTI will be chosen as the default by using the -v option to print
296       the  version information.  The "default-tcti" key-value pair will indi‐
297       cate which of the aforementioned TCTIs is the default.
298
299   Custom TCTIs
300       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
301       tools internally use dlopen(3), and the raw tcti-name value is used for
302       the lookup.  Thus, this could be a path to the shared library, or a li‐
303       brary name as understood by dlopen(3) semantics.
304

TCTI OPTIONS

306       This collection of options are used to configure the various known TCTI
307       modules available:
308
309       · device: For the device TCTI, the TPM character device file for use by
310         the device TCTI can be specified.  The default is /dev/tpm0.
311
312         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
313         vice:/dev/tpm0"
314
315       · mssim: For the mssim TCTI, the domain name or  IP  address  and  port
316         number  used  by  the  simulator  can  be specified.  The default are
317         127.0.0.1 and 2321.
318
319         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
320         TI="mssim:host=localhost,port=2321"
321
322       · abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
323         ries of simple key value pairs separated by a  ','  character.   Each
324         key and value string are separated by a '=' character.
325
326         · TCTI abrmd supports two keys:
327
328           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
329              string).
330
331           2. 'bus_type' : The type of the dbus instance (a string) limited to
332              'session' and 'system'.
333
334         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
335         ample.FooBar:
336
337         \--tcti=tabrmd:bus_name=com.example.FooBar
338
339         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
340         sion:
341
342         \--tcti:bus_type=session
343
344         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
345         ules.
346

EXAMPLES

348   Generate a quote with a TPM, then verify it
349              tpm2_createek -c 0x81010009 -G rsa -u ekpub.pem -f pem
350
351              tpm2_createak -C 0x81010009 -k 0x8101000a -G rsa -s rsassa -D sha256 \
352              -p akpub.pem -f pem -n ak.name
353
354              tpm2_quote -c 0x8101000a -l sha256:15,16,22 -q abc123 -m quote.out -s sig.out \
355              -o pcrs.out -g sha256
356
357              tpm2_checkquote -u akpub.pem -m quote.out -s sig.out -f pcrs.out -g sha256 \
358              -q abc123
359

Returns

361       Tools can return any of the following codes:
362
363       · 0 - Success.
364
365       · 1 - General non-specific error.
366
367       · 2 - Options handling error.
368
369       · 3 - Authentication error.
370
371       · 4 - TCTI related error.
372
373       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
374

BUGS

376       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
377

HELP

379       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
380
381
382
383tpm2-tools                                                  tpm2_checkquote(1)
Impressum