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

NAME

6       tpm2_ecdhkeygen(1)  -  Creates an ephemeral key and uses it to generate
7       the shared secret value using the parameters from a ECC public key.
8

SYNOPSIS

10       tpm2_ecdhkeygen [OPTIONS]
11

DESCRIPTION

13       tpm2_ecdhkeygen(1) - Creates an ephemeral key and uses it  to  generate
14       the shared secret value using the parameters from a ECC public key.
15

OPTIONS

17-c, --context=FILE:
18
19         Context object pointing to ECC public key.  Either a file or a handle
20         number.  See section "Context Object Format".
21
22-u, --public=FILE:
23
24         Output ECC point Q.
25
26-o, --output=FILE
27
28         Specify file path to save the calculated ecdh secret or Z point.
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
190       and sha384 hash
191
192       /tpm2_create -C parent.ctx -G ecc256:ec‐
193       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
194

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

321              tpm2_createprimary -C o -c prim.ctx -Q
322
323              tpm2_create -C prim.ctx -c key.ctx -u key.pub -r key.priv -G ecc256:ecdaa
324
325              tpm2_ecdhkeygen -u ecdh.pub -o ecdh.priv -c key.ctx
326

Returns

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

BUGS

343       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
344

HELP

346       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
347
348
349
350tpm2-tools                                                  tpm2_ecdhkeygen(1)
Impressum