1tpm2_incrementalselftest(1) General Commands Manualtpm2_incrementalselftest(1)
2
6 tpm2_incrementalselftest(1) - Request testing of specified algorithm
7 list
8
10 tpm2_incrementalselftest [OPTIONS] ALG_SPEC_LIST
11
13 tpm2_incrementalselftest(1) Request the TPM to perform testing on spec‐
14 ified algorithm and print a list of algorithm scheduled to be tested OR
15 remain to be tested but not scheduled.
16 The main interest of this command is to reduce delays that might occur
18 on cryptographic operations as TPM must test the algorithm prior using
19 it.
20
22 A space-separated list of algorithm suite to be tested. Algorithms
23 should follow the "formatting standards", see section "Algorithm Speci‐
24 fiers". Also, see section "Supported Hash Algorithms" for a list of
25 supported hash algorithms.
26 If ALG_SPEC_LIST is left empty, tpm2_incrementalselftest(1) will return
28 the list of algorithms left to be tested. Please note that in this
29 case these algorithms are NOT scheduled to be tested.
30 If ALG_SPEC_LIST is not empty, tpm2_incrementalselftest(1) will return
32 the list of algorithms that remains to be tested. This list contains
33 algorithms scheduled for testing AND algorithms that remains to be
34 tested and not yet scheduled. This can occur for instance if all AES
35 mode have not been already tested yet.
36
38 List of algorithms to be tested (implying scheduled) or remain to be
39 tested (not scheduled) is also printed in YAML format.
40 If none of the specified algorithm is printed, that means both that
42 they are already tested AND that these algorithms won't be tested
43 again.
44
46 This tool accepts no tool specific options.
47 References
50 Options that take algorithms support "nice-names".
51 There are two major algorithm specification string classes, simple and
53 complex. Only certain algorithms will be accepted by the TPM, based on
54 usage and conditions.
55 Simple specifiers
57 These are strings with no additional specification data. When creating
58 objects, non-specified portions of an object are assumed to defaults.
59 You can find the list of known "Simple Specifiers Below".
60 Asymmetric
62 • rsa
63 • ecc
65 Symmetric
67 • aes
68 • camellia
70 Hashing Algorithms
72 • sha1
73 • sha256
75 • sha384
77 • sha512
79 • sm3_256
81 • sha3_256
83 • sha3_384
85 • sha3_512
87 Keyed Hash
89 • hmac
90 • xor
92 Signing Schemes
94 • rsassa
95 • rsapss
97 • ecdsa
99 • ecdaa
101 • ecschnorr
103 Asymmetric Encryption Schemes
105 • oaep
106 • rsaes
108 • ecdh
110 Modes
112 • ctr
113 • ofb
115 • cbc
117 • cfb
119 • ecb
121 Misc
123 • null
124 Complex Specifiers
126 Objects, when specified for creation by the TPM, have numerous algo‐
127 rithms to populate in the public data. Things like type, scheme and
128 asymmetric details, key size, etc. Below is the general format for
129 specifying this data: <type>:<scheme>:<symmetric-details>
130 Type Specifiers
132 This portion of the complex algorithm specifier is required. The re‐
133 maining scheme and symmetric details will default based on the type
134 specified and the type of the object being created.
135 • aes - Default AES: aes128
137 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
139 If mode is not specified, defaults to null.
140 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
142 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
144 • ecc - Elliptical Curve, defaults to ecc256.
146 • ecc192 - 192 bit ECC
148 • ecc224 - 224 bit ECC
150 • ecc256 - 256 bit ECC
152 • ecc384 - 384 bit ECC
154 • ecc521 - 521 bit ECC
156 • rsa - Default RSA: rsa2048
158 • rsa1024 - RSA with 1024 bit keysize.
160 • rsa2048 - RSA with 2048 bit keysize.
162 • rsa4096 - RSA with 4096 bit keysize.
164 Scheme Specifiers
166 Next, is an optional field, it can be skipped.
167 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
169 Most signing schemes take a hash algorithm directly following the sign‐
170 ing scheme. If the hash algorithm is missing, it defaults to sha256.
171 Some take no arguments, and some take multiple arguments.
172 Hash Optional Scheme Specifiers
174 These scheme specifiers are followed by a dash and a valid hash algo‐
175 rithm, For example: oaep-sha256.
176 • oaep
178 • ecdh
180 • rsassa
182 • rsapss
184 • ecdsa
186 • ecschnorr
188 Multiple Option Scheme Specifiers
190 This scheme specifier is followed by a count (max size UINT16) then
191 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
192 ecdaa4-sha256. If no count is specified, it defaults to 4.
193 No Option Scheme Specifiers
195 This scheme specifier takes NO arguments. * rsaes
196 Symmetric Details Specifiers
198 This field is optional, and defaults based on the type of object being
199 created and it's attributes. Generally, any valid Symmetric specifier
200 from the Type Specifiers list should work. If not specified, an asym‐
201 metric objects symmetric details defaults to aes128cfb.
202 Examples
204 Create an rsa2048 key with an rsaes asymmetric encryption scheme
205 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
206 Create an ecc256 key with an ecdaa signing scheme with a count of 4
208 and sha384 hash
209 /tpm2_create -C parent.ctx -G ecc256:ec‐
211 daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
212
214 This collection of options are common to many programs and provide in‐
215 formation that many users may expect.
216 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
218 attempts to invoke the manpager for the tool, however, on failure
219 will output a short tool summary. This is the same behavior if the
220 "man" option argument is specified, however if explicit "man" is re‐
221 quested, the tool will provide errors from man on stderr. If the
222 "no-man" option if specified, or the manpager fails, the short op‐
223 tions will be output to stdout.
224 To successfully use the manpages feature requires the manpages to be
226 installed or on MANPATH, See man(1) for more details.
227 • -v, --version: Display version information for this tool, supported
229 tctis and exit.
230 • -V, --verbose: Increase the information that the tool prints to the
232 console during its execution. When using this option the file and
233 line number are printed.
234 • -Q, --quiet: Silence normal tool output to stdout.
236 • -Z, --enable-errata: Enable the application of errata fixups. Useful
238 if an errata fixup needs to be applied to commands sent to the TPM.
239 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
240 formation many users may expect.
241
243 The TCTI or "Transmission Interface" is the communication mechanism
244 with the TPM. TCTIs can be changed for communication with TPMs across
245 different mediums.
246 To control the TCTI, the tools respect:
248 1. The command line option -T or --tcti
250 2. The environment variable: TPM2TOOLS_TCTI.
252 Note: The command line option always overrides the environment vari‐
254 able.
255 The current known TCTIs are:
257 • tabrmd - The resource manager, called tabrmd
259 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
260 abrmd as a tcti name are synonymous.
261 • mssim - Typically used for communicating to the TPM software simula‐
263 tor.
264 • device - Used when talking directly to a TPM device file.
266 • none - Do not initalize a connection with the TPM. Some tools allow
268 for off-tpm options and thus support not using a TCTI. Tools that do
269 not support it will error when attempted to be used without a TCTI
270 connection. Does not support ANY options and MUST BE presented as
271 the exact text of "none".
272 The arguments to either the command line option or the environment
274 variable are in the form:
275 <tcti-name>:<tcti-option-config>
277 Specifying an empty string for either the <tcti-name> or <tcti-op‐
279 tion-config> results in the default being used for that portion respec‐
280 tively.
281 TCTI Defaults
283 When a TCTI is not specified, the default TCTI is searched for using
284 dlopen(3) semantics. The tools will search for tabrmd, device and
285 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
286 what TCTI will be chosen as the default by using the -v option to print
287 the version information. The "default-tcti" key-value pair will indi‐
288 cate which of the aforementioned TCTIs is the default.
289 Custom TCTIs
291 Any TCTI that implements the dynamic TCTI interface can be loaded. The
292 tools internally use dlopen(3), and the raw tcti-name value is used for
293 the lookup. Thus, this could be a path to the shared library, or a li‐
294 brary name as understood by dlopen(3) semantics.
295
297 This collection of options are used to configure the various known TCTI
298 modules available:
299 • device: For the device TCTI, the TPM character device file for use by
301 the device TCTI can be specified. The default is /dev/tpm0.
302 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
304 vice:/dev/tpm0"
305 • mssim: For the mssim TCTI, the domain name or IP address and port
307 number used by the simulator can be specified. The default are
308 127.0.0.1 and 2321.
309 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
311 TI="mssim:host=localhost,port=2321"
312 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
314 ries of simple key value pairs separated by a ',' character. Each
315 key and value string are separated by a '=' character.
316 • TCTI abrmd supports two keys:
318 1. 'bus_name' : The name of the tabrmd service on the bus (a
320 string).
321 2. 'bus_type' : The type of the dbus instance (a string) limited to
323 'session' and 'system'.
324 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
326 ample.FooBar:
327 \--tcti=tabrmd:bus_name=com.example.FooBar
329 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
331 sion:
332 \--tcti:bus_type=session
334 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
336 ules.
337
339 Request testing of RSA algorithm
340 tpm2_incrementalselftest rsa
341 Request testing of multiple algorithms
343 tpm2_incrementalselftest rsa ecc xor aes cbc
344
346 Algorithm suite specified can imply either testing the combination or
347 the complete suite, depending on TPM manufacturer implementation.
348 e.g : One TPM might only test AES with CTR mode if "aes ctr" is speci‐
350 fied. An other might also test complete AES mode list AND test ctr
351 mode.
352 If an algorithm has already been tested, this command won't permit
354 re-executing the test. Only issuing tpm2_selftest(1) in full-test mode
355 enabled will force re-testing.
356
358 Tools can return any of the following codes:
359 • 0 - Success.
361 • 1 - General non-specific error.
363 • 2 - Options handling error.
365 • 3 - Authentication error.
367 • 4 - TCTI related error.
369 • 5 - Non supported scheme. Applicable to tpm2_testparams.
371
373 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
374
376 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
377tpm2-tools tpm2_incrementalselftest(1)