1tpm2_incrementalselftest(1) General Commands Manualtpm2_incrementalselftest(1)
2
3
4

NAME

6       tpm2_incrementalselftest(1)  -  Request  testing of specified algorithm
7       list
8

SYNOPSIS

10       tpm2_incrementalselftest [OPTIONS] ALG_SPEC_LIST
11

DESCRIPTION

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
17       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

ALG_SPEC_LIST

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
27       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
31       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

Output

38       List  of  algorithms  to be tested (implying scheduled) or remain to be
39       tested (not scheduled) is also printed in YAML format.
40
41       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

OPTIONS

46       This tool accepts no tool specific options.
47
48   References

Algorithm Specifiers

50       Options that take algorithms support "nice-names".
51
52       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
56   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
61   Asymmetric
62       • rsa
63
64       • ecc
65
66   Symmetric
67       • aes
68
69       • camellia
70
71   Hashing Algorithms
72       • sha1
73
74       • sha256
75
76       • sha384
77
78       • sha512
79
80       • sm3_256
81
82       • sha3_256
83
84       • sha3_384
85
86       • sha3_512
87
88   Keyed Hash
89       • hmac
90
91       • xor
92
93   Signing Schemes
94       • rsassa
95
96       • rsapss
97
98       • ecdsa
99
100       • ecdaa
101
102       • ecschnorr
103
104   Asymmetric Encryption Schemes
105       • oaep
106
107       • rsaes
108
109       • ecdh
110
111   Modes
112       • ctr
113
114       • ofb
115
116       • cbc
117
118       • cfb
119
120       • ecb
121
122   Misc
123       • null
124
125   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
131   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
136       • aes - Default AES: aes128
137
138       • aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
139         If mode is not specified, defaults to null.
140
141       • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
142
143       • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
144
145       • ecc - Elliptical Curve, defaults to ecc256.
146
147       • ecc192 - 192 bit ECC
148
149       • ecc224 - 224 bit ECC
150
151       • ecc256 - 256 bit ECC
152
153       • ecc384 - 384 bit ECC
154
155       • ecc521 - 521 bit ECC
156
157       • rsa - Default RSA: rsa2048
158
159       • rsa1024 - RSA with 1024 bit keysize.
160
161       • rsa2048 - RSA with 2048 bit keysize.
162
163       • rsa4096 - RSA with 4096 bit keysize.
164
165   Scheme Specifiers
166       Next, is an optional field, it can be skipped.
167
168       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
173   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
177       • oaep
178
179       • ecdh
180
181       • rsassa
182
183       • rsapss
184
185       • ecdsa
186
187       • ecschnorr
188
189   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
194   No Option Scheme Specifiers
195       This scheme specifier takes NO arguments.  * rsaes
196
197   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
203   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
207   Create an ecc256 key with an ecdaa signing scheme with a count of 4
208       and sha384 hash
209
210       /tpm2_create -C parent.ctx -G ecc256:ec‐
211       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
212

COMMON OPTIONS

214       This collection of options are common to many programs and provide  in‐
215       formation that many users may expect.
216
217-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
225         To  successfully use the manpages feature requires the manpages to be
226         installed or on MANPATH, See man(1) for more details.
227
228-v, --version: Display version information for this  tool,  supported
229         tctis and exit.
230
231-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
235-Q, --quiet: Silence normal tool output to stdout.
236
237-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

TCTI Configuration

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
247       To control the TCTI, the tools respect:
248
249       1. The command line option -T or --tcti
250
251       2. The environment variable: TPM2TOOLS_TCTI.
252
253       Note: The command line option always overrides  the  environment  vari‐
254       able.
255
256       The current known TCTIs are:
257
258       • 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
262       • mssim  - Typically used for communicating to the TPM software simula‐
263         tor.
264
265       • device - Used when talking directly to a TPM device file.
266
267       • 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
273       The arguments to either the command  line  option  or  the  environment
274       variable are in the form:
275
276       <tcti-name>:<tcti-option-config>
277
278       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
282   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
290   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

TCTI OPTIONS

297       This collection of options are used to configure the various known TCTI
298       modules available:
299
300device: 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
303         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
304         vice:/dev/tpm0"
305
306        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
310         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
311         TI="mssim:host=localhost,port=2321"
312
313        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
317         • TCTI abrmd supports two keys:
318
319           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
320              string).
321
322           2. 'bus_type' : The type of the dbus instance (a string) limited to
323              'session' and 'system'.
324
325         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
326         ample.FooBar:
327
328         \--tcti=tabrmd:bus_name=com.example.FooBar
329
330         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
331         sion:
332
333         \--tcti:bus_type=session
334
335         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
336         ules.
337

EXAMPLES

339   Request testing of RSA algorithm
340              tpm2_incrementalselftest rsa
341
342   Request testing of multiple algorithms
343              tpm2_incrementalselftest rsa ecc xor aes cbc
344

NOTES

346       Algorithm suite specified can imply either testing the  combination  or
347       the complete suite, depending on TPM manufacturer implementation.
348
349       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
353       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

Returns

358       Tools can return any of the following codes:
359
360       • 0 - Success.
361
362       • 1 - General non-specific error.
363
364       • 2 - Options handling error.
365
366       • 3 - Authentication error.
367
368       • 4 - TCTI related error.
369
370       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
371

BUGS

373       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
374

HELP

376       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
377
378
379
380tpm2-tools                                         tpm2_incrementalselftest(1)
Impressum