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 and
208 sha384 hash
209 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
210 key.priv cryptographic algorithms ALGORITHM.
211
213 This collection of options are common to many programs and provide in‐
214 formation that many users may expect.
215 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
217 attempts to invoke the manpager for the tool, however, on failure
218 will output a short tool summary. This is the same behavior if the
219 “man” option argument is specified, however if explicit “man” is re‐
220 quested, the tool will provide errors from man on stderr. If the
221 “no-man” option if specified, or the manpager fails, the short op‐
222 tions will be output to stdout.
223 To successfully use the manpages feature requires the manpages to be
225 installed or on MANPATH, See man(1) for more details.
226 • -v, --version: Display version information for this tool, supported
228 tctis and exit.
229 • -V, --verbose: Increase the information that the tool prints to the
231 console during its execution. When using this option the file and
232 line number are printed.
233 • -Q, --quiet: Silence normal tool output to stdout.
235 • -Z, --enable-errata: Enable the application of errata fixups. Useful
237 if an errata fixup needs to be applied to commands sent to the TPM.
238 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
239 formation many users may expect.
240
242 The TCTI or “Transmission Interface” is the communication mechanism
243 with the TPM. TCTIs can be changed for communication with TPMs across
244 different mediums.
245 To control the TCTI, the tools respect:
247 1. The command line option -T or --tcti
249 2. The environment variable: TPM2TOOLS_TCTI.
251 Note: The command line option always overrides the environment vari‐
253 able.
254 The current known TCTIs are:
256 • tabrmd - The resource manager, called tabrmd
258 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
259 abrmd as a tcti name are synonymous.
260 • mssim - Typically used for communicating to the TPM software simula‐
262 tor.
263 • device - Used when talking directly to a TPM device file.
265 • none - Do not initalize a connection with the TPM. Some tools allow
267 for off-tpm options and thus support not using a TCTI. Tools that do
268 not support it will error when attempted to be used without a TCTI
269 connection. Does not support ANY options and MUST BE presented as
270 the exact text of “none”.
271 The arguments to either the command line option or the environment
273 variable are in the form:
274 <tcti-name>:<tcti-option-config>
276 Specifying an empty string for either the <tcti-name> or <tcti-op‐
278 tion-config> results in the default being used for that portion respec‐
279 tively.
280 TCTI Defaults
282 When a TCTI is not specified, the default TCTI is searched for using
283 dlopen(3) semantics. The tools will search for tabrmd, device and
284 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
285 what TCTI will be chosen as the default by using the -v option to print
286 the version information. The “default-tcti” key-value pair will indi‐
287 cate which of the aforementioned TCTIs is the default.
288 Custom TCTIs
290 Any TCTI that implements the dynamic TCTI interface can be loaded. The
291 tools internally use dlopen(3), and the raw tcti-name value is used for
292 the lookup. Thus, this could be a path to the shared library, or a li‐
293 brary name as understood by dlopen(3) semantics.
294
296 This collection of options are used to configure the various known TCTI
297 modules available:
298 • device: For the device TCTI, the TPM character device file for use by
300 the device TCTI can be specified. The default is /dev/tpm0.
301 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
303 vice:/dev/tpm0”
304 • mssim: For the mssim TCTI, the domain name or IP address and port
306 number used by the simulator can be specified. The default are
307 127.0.0.1 and 2321.
308 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
310 TI=“mssim:host=localhost,port=2321”
311 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
313 ries of simple key value pairs separated by a `,' character. Each
314 key and value string are separated by a `=' character.
315 • TCTI abrmd supports two keys:
317 1. `bus_name' : The name of the tabrmd service on the bus (a
319 string).
320 2. `bus_type' : The type of the dbus instance (a string) limited to
322 `session' and `system'.
323 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
325 ample.FooBar:
326 \--tcti=tabrmd:bus_name=com.example.FooBar
328 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
330 sion:
331 \--tcti:bus_type=session
333 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
335 ules.
336
338 Request testing of RSA algorithm
339 tpm2_incrementalselftest rsa
340 Request testing of multiple algorithms
342 tpm2_incrementalselftest rsa ecc xor aes cbc
343
345 Algorithm suite specified can imply either testing the combination or
346 the complete suite, depending on TPM manufacturer implementation.
347 e.g : One TPM might only test AES with CTR mode if “aes ctr” is speci‐
349 fied. An other might also test complete AES mode list AND test ctr
350 mode.
351 If an algorithm has already been tested, this command won’t permit
353 re-executing the test. Only issuing tpm2_selftest(1) in full-test mode
354 enabled will force re-testing.
355
357 Tools can return any of the following codes:
358 • 0 - Success.
360 • 1 - General non-specific error.
362 • 2 - Options handling error.
364 • 3 - Authentication error.
366 • 4 - TCTI related error.
368 • 5 - Non supported scheme. Applicable to tpm2_testparams.
370
372 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
373
375 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
376tpm2-tools tpm2_incrementalselftest(1)