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 • sm4
72 Hashing Algorithms
74 • sha1
75 • sha256
77 • sha384
79 • sha512
81 • sm3_256
83 • sha3_256
85 • sha3_384
87 • sha3_512
89 Keyed Hash
91 • hmac
92 • xor
94 Signing Schemes
96 • rsassa
97 • rsapss
99 • ecdsa
101 • ecdaa
103 • ecschnorr
105 • sm2
107 Asymmetric Encryption Schemes
109 • oaep
110 • rsaes
112 • ecdh
114 Modes
116 • ctr
117 • ofb
119 • cbc
121 • cfb
123 • ecb
125 Misc
127 • null
128 Complex Specifiers
130 Objects, when specified for creation by the TPM, have numerous algo‐
131 rithms to populate in the public data. Things like type, scheme and
132 asymmetric details, key size, etc. Below is the general format for
133 specifying this data: <type>:<scheme>:<symmetric-details>
134 Type Specifiers
136 This portion of the complex algorithm specifier is required. The re‐
137 maining scheme and symmetric details will default based on the type
138 specified and the type of the object being created.
139 • aes - Default AES: aes128
141 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
143 If mode is not specified, defaults to null.
144 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
146 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
148 • sm4 - Default SM4: sm4128
150 • sm4128 or sm4_128 <mode> - 128 bit SM4 with optional mode
152 (ctr|ofb|cbc|cfb|ecb). If mode is not specified, defaults to null.
153 • ecc - Elliptical Curve, defaults to ecc256.
155 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
157 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
159 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
161 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
163 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
165 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
167 • rsa - Default RSA: rsa2048
169 • rsa1024 - RSA with 1024 bit keysize.
171 • rsa2048 - RSA with 2048 bit keysize.
173 • rsa3072 - RSA with 3072 bit keysize.
175 • rsa4096 - RSA with 4096 bit keysize.
177 Scheme Specifiers
179 Next, is an optional field, it can be skipped.
180 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
182 Most signing schemes take a hash algorithm directly following the sign‐
183 ing scheme. If the hash algorithm is missing, it defaults to sha256.
184 Some take no arguments, and some take multiple arguments.
185 Hash Optional Scheme Specifiers
187 These scheme specifiers are followed by a dash and a valid hash algo‐
188 rithm, For example: oaep-sha256.
189 • oaep
191 • ecdh
193 • rsassa
195 • rsapss
197 • ecdsa
199 • ecschnorr
201 • sm2
203 Multiple Option Scheme Specifiers
205 This scheme specifier is followed by a count (max size UINT16) then
206 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
207 ecdaa4-sha256. If no count is specified, it defaults to 4.
208 No Option Scheme Specifiers
210 This scheme specifier takes NO arguments. * rsaes
211 Symmetric Details Specifiers
213 This field is optional, and defaults based on the type of object being
214 created and it’s attributes. Generally, any valid Symmetric specifier
215 from the Type Specifiers list should work. If not specified, an asym‐
216 metric objects symmetric details defaults to aes128cfb.
217 Examples
219 Create an rsa2048 key with an rsaes asymmetric encryption scheme
220 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
221 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
223 sha384 hash
224 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
225 key.priv cryptographic algorithms ALGORITHM.
226
228 This collection of options are common to many programs and provide in‐
229 formation that many users may expect.
230 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
232 attempts to invoke the manpager for the tool, however, on failure
233 will output a short tool summary. This is the same behavior if the
234 “man” option argument is specified, however if explicit “man” is re‐
235 quested, the tool will provide errors from man on stderr. If the
236 “no-man” option if specified, or the manpager fails, the short op‐
237 tions will be output to stdout.
238 To successfully use the manpages feature requires the manpages to be
240 installed or on MANPATH, See man(1) for more details.
241 • -v, --version: Display version information for this tool, supported
243 tctis and exit.
244 • -V, --verbose: Increase the information that the tool prints to the
246 console during its execution. When using this option the file and
247 line number are printed.
248 • -Q, --quiet: Silence normal tool output to stdout.
250 • -Z, --enable-errata: Enable the application of errata fixups. Useful
252 if an errata fixup needs to be applied to commands sent to the TPM.
253 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
254 formation many users may expect.
255
257 The TCTI or “Transmission Interface” is the communication mechanism
258 with the TPM. TCTIs can be changed for communication with TPMs across
259 different mediums.
260 To control the TCTI, the tools respect:
262 1. The command line option -T or --tcti
264 2. The environment variable: TPM2TOOLS_TCTI.
266 Note: The command line option always overrides the environment vari‐
268 able.
269 The current known TCTIs are:
271 • tabrmd - The resource manager, called tabrmd
273 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
274 abrmd as a tcti name are synonymous.
275 • mssim - Typically used for communicating to the TPM software simula‐
277 tor.
278 • device - Used when talking directly to a TPM device file.
280 • none - Do not initalize a connection with the TPM. Some tools allow
282 for off-tpm options and thus support not using a TCTI. Tools that do
283 not support it will error when attempted to be used without a TCTI
284 connection. Does not support ANY options and MUST BE presented as
285 the exact text of “none”.
286 The arguments to either the command line option or the environment
288 variable are in the form:
289 <tcti-name>:<tcti-option-config>
291 Specifying an empty string for either the <tcti-name> or <tcti-op‐
293 tion-config> results in the default being used for that portion respec‐
294 tively.
295 TCTI Defaults
297 When a TCTI is not specified, the default TCTI is searched for using
298 dlopen(3) semantics. The tools will search for tabrmd, device and
299 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
300 what TCTI will be chosen as the default by using the -v option to print
301 the version information. The “default-tcti” key-value pair will indi‐
302 cate which of the aforementioned TCTIs is the default.
303 Custom TCTIs
305 Any TCTI that implements the dynamic TCTI interface can be loaded. The
306 tools internally use dlopen(3), and the raw tcti-name value is used for
307 the lookup. Thus, this could be a path to the shared library, or a li‐
308 brary name as understood by dlopen(3) semantics.
309
311 This collection of options are used to configure the various known TCTI
312 modules available:
313 • device: For the device TCTI, the TPM character device file for use by
315 the device TCTI can be specified. The default is /dev/tpm0.
316 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
318 vice:/dev/tpm0”
319 • mssim: For the mssim TCTI, the domain name or IP address and port
321 number used by the simulator can be specified. The default are
322 127.0.0.1 and 2321.
323 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
325 TI=“mssim:host=localhost,port=2321”
326 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
328 ries of simple key value pairs separated by a `,' character. Each
329 key and value string are separated by a `=' character.
330 • TCTI abrmd supports two keys:
332 1. `bus_name' : The name of the tabrmd service on the bus (a
334 string).
335 2. `bus_type' : The type of the dbus instance (a string) limited to
337 `session' and `system'.
338 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
340 ample.FooBar:
341 \--tcti=tabrmd:bus_name=com.example.FooBar
343 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
345 sion:
346 \--tcti:bus_type=session
348 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
350 ules.
351
353 Request testing of RSA algorithm
354 tpm2_incrementalselftest rsa
355 Request testing of multiple algorithms
357 tpm2_incrementalselftest rsa ecc xor aes cbc
358
360 Algorithm suite specified can imply either testing the combination or
361 the complete suite, depending on TPM manufacturer implementation.
362 e.g : One TPM might only test AES with CTR mode if “aes ctr” is speci‐
364 fied. An other might also test complete AES mode list AND test ctr
365 mode.
366 If an algorithm has already been tested, this command won’t permit
368 re-executing the test. Only issuing tpm2_selftest(1) in full-test mode
369 enabled will force re-testing.
370
372 Tools can return any of the following codes:
373 • 0 - Success.
375 • 1 - General non-specific error.
377 • 2 - Options handling error.
379 • 3 - Authentication error.
381 • 4 - TCTI related error.
383 • 5 - Non supported scheme. Applicable to tpm2_testparams.
385
387 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
388
390 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
391 fo/tpm2)
392tpm2-tools tpm2_incrementalselftest(1)