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
246       and sha384 hash
247
248       /tpm2_create -C parent.ctx -G ecc256:ec‐
249       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
250

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

Signature Format Specifiers

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

EXAMPLES

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

Returns

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

BUGS

441       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
442

HELP

444       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
445
446
447
448tpm2-tools                                             tpm2_verifysignature(1)