1tpm2_ecephemeral(1)         General Commands Manual        tpm2_ecephemeral(1)
2
3
4

NAME

6       tpm2_ecephemeral(1)  -  Creates an ephemeral key for use in a two-phase
7       key exchange protocol.
8

SYNOPSIS

10       tpm2_ecephemeral [OPTIONS]
11

DESCRIPTION

13       tpm2_ecephemeral(1) - Creates an ephemeral key for use in  a  two-phase
14       key exchange protocol.
15

OPTIONS

17ARGUMENT=ALGORITHM:
18
19         Specify the ECC curve.  Example ecc521.
20
21-u, --public=FILE
22
23         Specify the file path to save the ephemeral public point Q ≔ [r]G.
24
25-t, --counter=FILE
26
27         Specify  file  path  to  save the least-significant 16 bits of commit
28         count.
29
30   References

Algorithm Specifiers

32       Options that take algorithms support “nice-names”.
33
34       There are two major algorithm specification string classes, simple  and
35       complex.  Only certain algorithms will be accepted by the TPM, based on
36       usage and conditions.
37
38   Simple specifiers
39       These are strings with no additional specification data.  When creating
40       objects,  non-specified  portions of an object are assumed to defaults.
41       You can find the list of known “Simple Specifiers Below”.
42
43   Asymmetric
44       • rsa
45
46       • ecc
47
48   Symmetric
49       • aes
50
51       • camellia
52
53   Hashing Algorithms
54       • sha1
55
56       • sha256
57
58       • sha384
59
60       • sha512
61
62       • sm3_256
63
64       • sha3_256
65
66       • sha3_384
67
68       • sha3_512
69
70   Keyed Hash
71       • hmac
72
73       • xor
74
75   Signing Schemes
76       • rsassa
77
78       • rsapss
79
80       • ecdsa
81
82       • ecdaa
83
84       • ecschnorr
85
86   Asymmetric Encryption Schemes
87       • oaep
88
89       • rsaes
90
91       • ecdh
92
93   Modes
94       • ctr
95
96       • ofb
97
98       • cbc
99
100       • cfb
101
102       • ecb
103
104   Misc
105       • null
106
107   Complex Specifiers
108       Objects, when specified for creation by the TPM,  have  numerous  algo‐
109       rithms  to  populate  in the public data.  Things like type, scheme and
110       asymmetric details, key size, etc.  Below is  the  general  format  for
111       specifying this data: <type>:<scheme>:<symmetric-details>
112
113   Type Specifiers
114       This  portion  of the complex algorithm specifier is required.  The re‐
115       maining scheme and symmetric details will default  based  on  the  type
116       specified and the type of the object being created.
117
118       • aes - Default AES: aes128
119
120       • aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
121         If mode is not specified, defaults to null.
122
123       • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
124
125       • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
126
127       • ecc - Elliptical Curve, defaults to ecc256.
128
129       • ecc192 - 192 bit ECC
130
131       • ecc224 - 224 bit ECC
132
133       • ecc256 - 256 bit ECC
134
135       • ecc384 - 384 bit ECC
136
137       • ecc521 - 521 bit ECC
138
139       • rsa - Default RSA: rsa2048
140
141       • rsa1024 - RSA with 1024 bit keysize.
142
143       • rsa2048 - RSA with 2048 bit keysize.
144
145       • rsa4096 - RSA with 4096 bit keysize.
146
147   Scheme Specifiers
148       Next, is an optional field, it can be skipped.
149
150       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
151       Most signing schemes take a hash algorithm directly following the sign‐
152       ing scheme.  If the hash algorithm is missing, it defaults  to  sha256.
153       Some take no arguments, and some take multiple arguments.
154
155   Hash Optional Scheme Specifiers
156       These  scheme  specifiers are followed by a dash and a valid hash algo‐
157       rithm, For example: oaep-sha256.
158
159       • oaep
160
161       • ecdh
162
163       • rsassa
164
165       • rsapss
166
167       • ecdsa
168
169       • ecschnorr
170
171   Multiple Option Scheme Specifiers
172       This scheme specifier is followed by a count  (max  size  UINT16)  then
173       followed by a dash(-) and a valid hash algorithm.  * ecdaa For example,
174       ecdaa4-sha256.  If no count is specified, it defaults to 4.
175
176   No Option Scheme Specifiers
177       This scheme specifier takes NO arguments.  * rsaes
178
179   Symmetric Details Specifiers
180       This field is optional, and defaults based on the type of object  being
181       created  and it’s attributes.  Generally, any valid Symmetric specifier
182       from the Type Specifiers list should work.  If not specified, an  asym‐
183       metric objects symmetric details defaults to aes128cfb.
184
185   Examples
186   Create an rsa2048 key with an rsaes asymmetric encryption scheme
187       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
188
189   Create  an  ecc256  key  with an ecdaa signing scheme with a count of 4 and
190       sha384 hash
191       /tpm2_create  -C  parent.ctx  -G  ecc256:ecdaa4-sha384  -u  key.pub  -r
192       key.priv cryptographic algorithms ALGORITHM.
193

COMMON OPTIONS

195       This  collection of options are common to many programs and provide in‐
196       formation that many users may expect.
197
198-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
199         attempts  to  invoke  the  manpager for the tool, however, on failure
200         will output a short tool summary.  This is the same behavior  if  the
201         “man”  option argument is specified, however if explicit “man” is re‐
202         quested, the tool will provide errors from man  on  stderr.   If  the
203         “no-man”  option  if  specified, or the manpager fails, the short op‐
204         tions will be output to stdout.
205
206         To successfully use the manpages feature requires the manpages to  be
207         installed or on MANPATH, See man(1) for more details.
208
209-v,  --version:  Display version information for this tool, supported
210         tctis and exit.
211
212-V, --verbose: Increase the information that the tool prints  to  the
213         console  during  its  execution.  When using this option the file and
214         line number are printed.
215
216-Q, --quiet: Silence normal tool output to stdout.
217
218-Z, --enable-errata: Enable the application of errata fixups.  Useful
219         if  an  errata fixup needs to be applied to commands sent to the TPM.
220         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
221         formation many users may expect.
222

TCTI Configuration

224       The  TCTI  or  “Transmission  Interface” is the communication mechanism
225       with the TPM.  TCTIs can be changed for communication with TPMs  across
226       different mediums.
227
228       To control the TCTI, the tools respect:
229
230       1. The command line option -T or --tcti
231
232       2. The environment variable: TPM2TOOLS_TCTI.
233
234       Note:  The  command  line option always overrides the environment vari‐
235       able.
236
237       The current known TCTIs are:
238
239       • tabrmd     -     The     resource     manager,     called      tabrmd
240         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
241         abrmd as a tcti name are synonymous.
242
243       • mssim - Typically used for communicating to the TPM software  simula‐
244         tor.
245
246       • device - Used when talking directly to a TPM device file.
247
248       • none  - Do not initalize a connection with the TPM.  Some tools allow
249         for off-tpm options and thus support not using a TCTI.  Tools that do
250         not  support  it  will error when attempted to be used without a TCTI
251         connection.  Does not support ANY options and MUST  BE  presented  as
252         the exact text of “none”.
253
254       The  arguments  to  either  the  command line option or the environment
255       variable are in the form:
256
257       <tcti-name>:<tcti-option-config>
258
259       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
260       tion-config> results in the default being used for that portion respec‐
261       tively.
262
263   TCTI Defaults
264       When a TCTI is not specified, the default TCTI is  searched  for  using
265       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
266       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
267       what TCTI will be chosen as the default by using the -v option to print
268       the version information.  The “default-tcti” key-value pair will  indi‐
269       cate which of the aforementioned TCTIs is the default.
270
271   Custom TCTIs
272       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
273       tools internally use dlopen(3), and the raw tcti-name value is used for
274       the lookup.  Thus, this could be a path to the shared library, or a li‐
275       brary name as understood by dlopen(3) semantics.
276

TCTI OPTIONS

278       This collection of options are used to configure the various known TCTI
279       modules available:
280
281device: For the device TCTI, the TPM character device file for use by
282         the device TCTI can be specified.  The default is /dev/tpm0.
283
284         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
285         vice:/dev/tpm0”
286
287mssim:  For  the  mssim  TCTI, the domain name or IP address and port
288         number used by the simulator  can  be  specified.   The  default  are
289         127.0.0.1 and 2321.
290
291         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
292         TI=“mssim:host=localhost,port=2321”
293
294abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
295         ries  of  simple  key value pairs separated by a `,' character.  Each
296         key and value string are separated by a `=' character.
297
298         • TCTI abrmd supports two keys:
299
300           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
301              string).
302
303           2. `bus_type' : The type of the dbus instance (a string) limited to
304              `session' and `system'.
305
306         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
307         ample.FooBar:
308
309                \--tcti=tabrmd:bus_name=com.example.FooBar
310
311         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
312         sion:
313
314                \--tcti:bus_type=session
315
316         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
317         ules.
318

EXAMPLES

320              tpm2_ecephemeral -u ecc.q -t ecc.ctr ecc256
321

Returns

323       Tools can return any of the following codes:
324
325       • 0 - Success.
326
327       • 1 - General non-specific error.
328
329       • 2 - Options handling error.
330
331       • 3 - Authentication error.
332
333       • 4 - TCTI related error.
334
335       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
336

BUGS

338       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
339

HELP

341       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
342
343
344
345tpm2-tools                                                 tpm2_ecephemeral(1)
Impressum