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

NAME

6       tpm2_verifysignature(1) - Validates a signature using the TPM.
7

SYNOPSIS

9       tpm2_verifysignature [OPTIONS]
10

DESCRIPTION

12       tpm2_verifysignature(1) - Uses loaded keys to validate a signature on a
13       message with the message digest passed to the TPM.   If  the  signature
14       check  succeeds,  then the TPM will produce a TPMT_TK_VERIFIED.  Other‐
15       wise, the TPM shall return TPM_RC_SIGNATURE.  If object  references  an
16       asymmetric  key, only the public portion of the key needs to be loaded.
17       If object references a symmetric key, both the public and private  por‐
18       tions need to be loaded.
19

OPTIONS

21       • -c, --key-context=OBJECT:
22
23         Context  object for the key context used for the operation.  Either a
24         file or a handle number.  See section “Context Object Format”.
25
26       • -g, --hash-algorithm=ALGORITHM:
27
28         The hash algorithm used to digest  the  message.   Algorithms  should
29         follow  the  “formatting  standards”,  see  section “Algorithm Speci‐
30         fiers”.  Also, see section “Supported Hash Algorithms” for a list  of
31         supported hash algorithms.
32
33       • -m, --message=FILE:
34
35         The message file, containing the content to be digested.
36
37       • -d, --digest=FILE:
38
39         The input hash file, containing the hash of the message.  If this op‐
40         tion is selected, then the message (-m) and algorithm (-g) options do
41         not need to be specified.
42
43       • -s, --signature=FILE:
44
45         The input signature file of the signature to be validated.
46
47       • -f, --scheme=SCHEME:
48
49         The  signing  scheme  that was used to sign the message.  This option
50         should only be specified if the signature comes in  from  a  non  tss
51         standard,  like  openssl.  See “Signature format specifiers” for more
52         details.  The tss format contains the signature metadata required  to
53         understand it’s signature scheme.
54
55         Signing schemes should follow the “formatting standards”, see section
56         “Algorithm Specifiers”.
57
58       • --format=SCHEME:
59
60         Deprecated.  Same as --scheme.
61
62       • -t, --ticket=FILE:
63
64         The ticket file to record the validation structure.
65
66   References

Context Object Format

68       The type of a context object, whether it is a handle or file  name,  is
69       determined according to the following logic in-order:
70
71       • If the argument is a file path, then the file is loaded as a restored
72         TPM transient object.
73
74       • If the argument is a prefix match on one of:
75
76         • owner: the owner hierarchy
77
78         • platform: the platform hierarchy
79
80         • endorsement: the endorsement hierarchy
81
82         • lockout: the lockout control persistent object
83
84       • If the argument argument can be loaded as a number it will  be  treat
85         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
86

Algorithm Specifiers

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

COMMON OPTIONS

251       This collection of options are common to many programs and provide  in‐
252       formation that many users may expect.
253
254       • -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
255         attempts to invoke the manpager for the  tool,  however,  on  failure
256         will  output  a short tool summary.  This is the same behavior if the
257         “man” option argument is specified, however if explicit “man” is  re‐
258         quested,  the  tool  will  provide errors from man on stderr.  If the
259         “no-man” option if specified, or the manpager fails,  the  short  op‐
260         tions will be output to stdout.
261
262         To  successfully use the manpages feature requires the manpages to be
263         installed or on MANPATH, See man(1) for more details.
264
265       • -v, --version: Display version information for this  tool,  supported
266         tctis and exit.
267
268       • -V,  --verbose:  Increase the information that the tool prints to the
269         console during its execution.  When using this option  the  file  and
270         line number are printed.
271
272       • -Q, --quiet: Silence normal tool output to stdout.
273
274       • -Z, --enable-errata: Enable the application of errata fixups.  Useful
275         if an errata fixup needs to be applied to commands sent to  the  TPM.
276         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
277         formation many users may expect.
278

TCTI Configuration

280       The TCTI or “Transmission Interface”  is  the  communication  mechanism
281       with  the TPM.  TCTIs can be changed for communication with TPMs across
282       different mediums.
283
284       To control the TCTI, the tools respect:
285
286       1. The command line option -T or --tcti
287
288       2. The environment variable: TPM2TOOLS_TCTI.
289
290       Note: The command line option always overrides  the  environment  vari‐
291       able.
292
293       The current known TCTIs are:
294
295       • tabrmd      -     The     resource     manager,     called     tabrmd
296         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
297         abrmd as a tcti name are synonymous.
298
299       • mssim  - Typically used for communicating to the TPM software simula‐
300         tor.
301
302       • device - Used when talking directly to a TPM device file.
303
304       • none - Do not initalize a connection with the TPM.  Some tools  allow
305         for off-tpm options and thus support not using a TCTI.  Tools that do
306         not support it will error when attempted to be used  without  a  TCTI
307         connection.   Does  not  support ANY options and MUST BE presented as
308         the exact text of “none”.
309
310       The arguments to either the command  line  option  or  the  environment
311       variable are in the form:
312
313       <tcti-name>:<tcti-option-config>
314
315       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
316       tion-config> results in the default being used for that portion respec‐
317       tively.
318
319   TCTI Defaults
320       When  a  TCTI  is not specified, the default TCTI is searched for using
321       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
322       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
323       what TCTI will be chosen as the default by using the -v option to print
324       the  version information.  The “default-tcti” key-value pair will indi‐
325       cate which of the aforementioned TCTIs is the default.
326
327   Custom TCTIs
328       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
329       tools internally use dlopen(3), and the raw tcti-name value is used for
330       the lookup.  Thus, this could be a path to the shared library, or a li‐
331       brary name as understood by dlopen(3) semantics.
332

TCTI OPTIONS

334       This collection of options are used to configure the various known TCTI
335       modules available:
336
337       • device: For the device TCTI, the TPM character device file for use by
338         the device TCTI can be specified.  The default is /dev/tpm0.
339
340         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
341         vice:/dev/tpm0”
342
343       • mssim: For the mssim TCTI, the domain name or  IP  address  and  port
344         number  used  by  the  simulator  can  be specified.  The default are
345         127.0.0.1 and 2321.
346
347         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
348         TI=“mssim:host=localhost,port=2321”
349
350       • abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
351         ries of simple key value pairs separated by a  `,'  character.   Each
352         key and value string are separated by a `=' character.
353
354         • TCTI abrmd supports two keys:
355
356           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
357              string).
358
359           2. `bus_type' : The type of the dbus instance (a string) limited to
360              `session' and `system'.
361
362         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
363         ample.FooBar:
364
365                \--tcti=tabrmd:bus_name=com.example.FooBar
366
367         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
368         sion:
369
370                \--tcti:bus_type=session
371
372         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
373         ules.
374

Signature Format Specifiers

376       Format selection for the signature output file.  tss (the default) will
377       output a binary blob according to the TPM 2.0 specification and any po‐
378       tential compiler padding.  The option plain will output the plain  sig‐
379       nature data as defined by the used cryptographic algorithm.
380

EXAMPLES

382   Sign and verify with the TPM using the endorsement hierarchy
383              tpm2_createprimary -C e -c primary.ctx
384
385              tpm2_create -G rsa -u rsa.pub -r rsa.priv -C primary.ctx
386
387              tpm2_load -C primary.ctx -u rsa.pub -r rsa.priv -c rsa.ctx
388
389              echo "my message > message.dat
390
391              tpm2_sign -c rsa.ctx -g sha256 -m message.dat -s sig.rssa
392
393              tpm2_verifysignature -c rsa.ctx -g sha256 -m message.dat -s sig.rssa
394
395   Sign with openssl and verify with the TPM
396              # Generate an ECC key
397              openssl ecparam -name prime256v1 -genkey -noout -out private.ecc.pem
398
399              openssl ec -in private.ecc.pem -out public.ecc.pem -pubout
400
401              # Generate a hash to sign (OSSL needs the hash of the message)
402              echo "data to sign" > data.in.raw
403
404              sha256sum data.in.raw | awk '{ print "000000 " $1 }' | \
405              xxd -r -c 32 > data.in.digest
406
407              # Load the private key for signing
408              tpm2_loadexternal -Q -G ecc -r private.ecc.pem -c key.ctx
409
410              # Sign in the TPM and verify with OSSL
411              tpm2_sign -Q -c key.ctx -g sha256 -d data.in.digest -f plain -s data.out.signed
412
413              openssl dgst -verify public.ecc.pem -keyform pem -sha256 \
414              -signature data.out.signed data.in.raw
415
416              # Sign with openssl and verify with TPM
417              openssl dgst -sha256 -sign private.ecc.pem -out data.out.signed data.in.raw
418
419              tpm2_verifysignature -Q -c key.ctx -g sha256 -m data.in.raw -f ecdsa \
420              -s data.out.signed
421

Returns

423       Tools can return any of the following codes:
424
425       • 0 - Success.
426
427       • 1 - General non-specific error.
428
429       • 2 - Options handling error.
430
431       • 3 - Authentication error.
432
433       • 4 - TCTI related error.
434
435       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
436

BUGS

438       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
439

HELP

441       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
442
443
444
445tpm2-tools                                             tpm2_verifysignature(1)