1tpm2_verifysignature(1) General Commands Manual tpm2_verifysignature(1)
2
6 tpm2_verifysignature(1) - Validates a signature using the TPM.
7
9 tpm2_verifysignature [OPTIONS]
10
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
21 · -c, --key-context=OBJECT:
22 Context object for the key context used for the operation. Either a
24 file or a handle number. See section "Context Object Format".
25 · -g, --hash-algorithm=ALGORITHM:
27 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 · -m, --message=FILE:
34 The message file, containing the content to be digested.
36 · -d, --digest=FILE:
38 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 · -s, --signature=FILE:
44 The input signature file of the signature to be validated.
46 · -f, --format=FORMAT:
48 Set the input signature file to a specified format. The default is
50 the tpm2.0 TPMT_SIGNATURE data format, however different schemes can
51 be selected if the data came from an external source like OpenSSL.
52 The tool currently only supports rsassa.
53 · -t, --ticket=FILE:
55 The ticket file to record the validation structure.
57 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 · If the argument is a file path, then the file is loaded as a restored
64 TPM transient object.
65 · If the argument is a prefix match on one of:
67 · owner: the owner hierarchy
69 · platform: the platform hierarchy
71 · endorsement: the endorsement hierarchy
73 · lockout: the lockout control persistent object
75 · 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 Options that take algorithms support "nice-names".
81 There are two major algorithm specification string classes, simple and
83 complex. Only certain algorithms will be accepted by the TPM, based on
84 usage and conditions.
85 Simple specifiers
87 These are strings with no additional specification data. When creating
88 objects, non-specified portions of an object are assumed to defaults.
89 You can find the list of known "Simple Specifiers Below".
90 Asymmetric
92 · rsa
93 · ecc
95 Symmetric
97 · aes
98 · camellia
100 Hashing Algorithms
102 · sha1
103 · sha256
105 · sha384
107 · sha512
109 · sm3_256
111 · sha3_256
113 · sha3_384
115 · sha3_512
117 Keyed Hash
119 · hmac
120 · xor
122 Signing Schemes
124 · rsassa
125 · rsapss
127 · ecdsa
129 · ecdaa
131 · ecschnorr
133 Asymmetric Encryption Schemes
135 · oaep
136 · rsaes
138 · ecdh
140 Modes
142 · ctr
143 · ofb
145 · cbc
147 · cfb
149 · ecb
151 Misc
153 · null
154 Complex Specifiers
156 Objects, when specified for creation by the TPM, have numerous algo‐
157 rithms to populate in the public data. Things like type, scheme and
158 asymmetric details, key size, etc. Below is the general format for
159 specifying this data: <type>:<scheme>:<symmetric-details>
160 Type Specifiers
162 This portion of the complex algorithm specifier is required. The re‐
163 maining scheme and symmetric details will default based on the type
164 specified and the type of the object being created.
165 · aes - Default AES: aes128
167 · aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
169 If mode is not specified, defaults to null.
170 · aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
172 · aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
174 · ecc - Elliptical Curve, defaults to ecc256.
176 · ecc192 - 192 bit ECC
178 · ecc224 - 224 bit ECC
180 · ecc256 - 256 bit ECC
182 · ecc384 - 384 bit ECC
184 · ecc521 - 521 bit ECC
186 · rsa - Default RSA: rsa2048
188 · rsa1024 - RSA with 1024 bit keysize.
190 · rsa2048 - RSA with 2048 bit keysize.
192 · rsa4096 - RSA with 4096 bit keysize.
194 Scheme Specifiers
196 Next, is an optional field, it can be skipped.
197 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
199 Most signing schemes take a hash algorithm directly following the sign‐
200 ing scheme. If the hash algorithm is missing, it defaults to sha256.
201 Some take no arguments, and some take multiple arguments.
202 Hash Optional Scheme Specifiers
204 These scheme specifiers are followed by a dash and a valid hash algo‐
205 rithm, For example: oaep-sha256.
206 · oaep
208 · ecdh
210 · rsassa
212 · rsapss
214 · ecdsa
216 · ecschnorr
218 Multiple Option Scheme Specifiers
220 This scheme specifier is followed by a count (max size UINT16) then
221 folloed by a dash(-) and a valid hash algorithm. * ecdaa For example,
222 ecdaa4-sha256. If no count is specified, it defaults to 4.
223 No Option Scheme Specifiers
225 This scheme specifier takes NO arguments. * rsaes
226 Symmetric Details Specifiers
228 This field is optional, and defaults based on the type of object being
229 created and it's attributes. Generally, any valid Symmetric specifier
230 from the Type Specifiers list should work. If not specified, an asym‐
231 metric objects symmetric details defaults to aes128cfb.
232 Examples
234 Create an rsa2048 key with an rsaes asymmetric encryption scheme
235 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
236 Create an ecc256 key with an ecdaa signing scheme with a count of 4
238 and sha384 hash
239 /tpm2_create -C parent.ctx -G ecc256:ec‐
241 daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
242
244 This collection of options are common to many programs and provide in‐
245 formation that many users may expect.
246 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
248 attempts to invoke the manpager for the tool, however, on failure
249 will output a short tool summary. This is the same behavior if the
250 "man" option argument is specified, however if explicit "man" is re‐
251 quested, the tool will provide errors from man on stderr. If the
252 "no-man" option if specified, or the manpager fails, the short op‐
253 tions will be output to stdout.
254 To successfully use the manpages feature requires the manpages to be
256 installed or on MANPATH, See man(1) for more details.
257 · -v, --version: Display version information for this tool, supported
259 tctis and exit.
260 · -V, --verbose: Increase the information that the tool prints to the
262 console during its execution. When using this option the file and
263 line number are printed.
264 · -Q, --quiet: Silence normal tool output to stdout.
266 · -Z, --enable-errata: Enable the application of errata fixups. Useful
268 if an errata fixup needs to be applied to commands sent to the TPM.
269 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
270 formation many users may expect.
271
273 The TCTI or "Transmission Interface" is the communication mechanism
274 with the TPM. TCTIs can be changed for communication with TPMs across
275 different mediums.
276 To control the TCTI, the tools respect:
278 1. The command line option -T or --tcti
280 2. The environment variable: TPM2TOOLS_TCTI.
282 Note: The command line option always overrides the environment vari‐
284 able.
285 The current known TCTIs are:
287 · tabrmd - The resource manager, called tabrmd
289 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
290 abrmd as a tcti name are synonymous.
291 · mssim - Typically used for communicating to the TPM software simula‐
293 tor.
294 · device - Used when talking directly to a TPM device file.
296 · none - Do not initalize a connection with the TPM. Some tools allow
298 for off-tpm options and thus support not using a TCTI. Tools that do
299 not support it will error when attempted to be used without a TCTI
300 connection. Does not support ANY options and MUST BE presented as
301 the exact text of "none".
302 The arguments to either the command line option or the environment
304 variable are in the form:
305 <tcti-name>:<tcti-option-config>
307 Specifying an empty string for either the <tcti-name> or <tcti-op‐
309 tion-config> results in the default being used for that portion respec‐
310 tively.
311 TCTI Defaults
313 When a TCTI is not specified, the default TCTI is searched for using
314 dlopen(3) semantics. The tools will search for tabrmd, device and
315 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
316 what TCTI will be chosen as the default by using the -v option to print
317 the version information. The "default-tcti" key-value pair will indi‐
318 cate which of the aforementioned TCTIs is the default.
319 Custom TCTIs
321 Any TCTI that implements the dynamic TCTI interface can be loaded. The
322 tools internally use dlopen(3), and the raw tcti-name value is used for
323 the lookup. Thus, this could be a path to the shared library, or a li‐
324 brary name as understood by dlopen(3) semantics.
325
327 This collection of options are used to configure the various known TCTI
328 modules available:
329 · device: For the device TCTI, the TPM character device file for use by
331 the device TCTI can be specified. The default is /dev/tpm0.
332 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
334 vice:/dev/tpm0"
335 · mssim: For the mssim TCTI, the domain name or IP address and port
337 number used by the simulator can be specified. The default are
338 127.0.0.1 and 2321.
339 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
341 TI="mssim:host=localhost,port=2321"
342 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
344 ries of simple key value pairs separated by a ',' character. Each
345 key and value string are separated by a '=' character.
346 · TCTI abrmd supports two keys:
348 1. 'bus_name' : The name of the tabrmd service on the bus (a
350 string).
351 2. 'bus_type' : The type of the dbus instance (a string) limited to
353 'session' and 'system'.
354 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
356 ample.FooBar:
357 \--tcti=tabrmd:bus_name=com.example.FooBar
359 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
361 sion:
362 \--tcti:bus_type=session
364 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
366 ules. # Signature Format Specifiers
367 Format selection for the signature output file. tss (the default) will
369 output a binary blob according to the TPM 2.0 specification and any po‐
370 tential compiler padding. The option plain will output the plain sig‐
371 nature data as defined by the used cryptographic algorithm.
372
374 Sign and verify with the TPM using the endorsement
375 hierarchy
376 tpm2_createprimary -C e -c primary.ctx
378 tpm2_create -G rsa -u rsa.pub -r rsa.priv -C primary.ctx
380 tpm2_load -C primary.ctx -u rsa.pub -r rsa.priv -c rsa.ctx
382 echo "my message > message.dat
384 tpm2_sign -c rsa.ctx -g sha256 -m message.dat -s sig.rssa
386 tpm2_verifysignature -c rsa.ctx -g sha256 -m message.dat -s sig.rssa
388 Sign with openssl and verify with the TPM
390 # Generate an ECC key
391 openssl ecparam -name prime256v1 -genkey -noout -out private.ecc.pem
392 openssl ec -in private.ecc.pem -out public.ecc.pem -pubout
394 # Generate a hash to sign (OSSL needs the hash of the message)
396 echo "data to sign" > data.in.raw
397 sha256sum data.in.raw | awk '{ print "000000 " $1 }' | \
399 xxd -r -c 32 > data.in.digest
400 # Load the private key for signing
402 tpm2_loadexternal -Q -G ecc -r private.ecc.pem -c key.ctx
403 # Sign in the TPM and verify with OSSL
405 tpm2_sign -Q -c key.ctx -g sha256 -d data.in.digest -f plain -s data.out.signed
406 openssl dgst -verify public.ecc.pem -keyform pem -sha256 \
408 -signature data.out.signed data.in.raw
409 # Sign with openssl and verify with TPM
411 openssl dgst -sha256 -sign private.ecc.pem -out data.out.signed data.in.raw
412 tpm2_verifysignature -Q -c key.ctx -g sha256 -m data.in.raw -f ecdsa \
414 -s data.out.signed
415
417 Tools can return any of the following codes:
418 · 0 - Success.
420 · 1 - General non-specific error.
422 · 2 - Options handling error.
424 · 3 - Authentication error.
426 · 4 - TCTI related error.
428 · 5 - Non supported scheme. Applicable to tpm2_testparams.
430
432 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
433
435 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
436tpm2-tools tpm2_verifysignature(1)