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

NAME

6       tpm2_createek(1) - Generate TCG profile compliant endorsement key.
7

SYNOPSIS

9       tpm2_createek [OPTIONS]
10

DESCRIPTION

12       tpm2_createek(1) - Generate TCG profile compliant endorsement key (EK),
13       which is the primary object of the endorsement hierarchy.
14
15       If a transient object is generated the  tool  outputs  a  context  file
16       specified with -c.
17
18       Refer       to:       <http://www.trustedcomputinggroup.org/files/stat
19       ic_page_files/7CAA5687-1A4B-B294-D04080D058E86C5F>
20

OPTIONS

22       · -P, --eh-auth=AUTH:
23
24         The authorization value for the endorsement hierarchy
25
26       · -p, --ek-auth=AUTH:
27
28         The authorization value for the primary object (endorsement key) cre‐
29         ated.
30
31       · -w, --owner-auth=AUTH
32
33         The authorization value for the owner hierarchy.
34
35       · -c, --ek-context=OBJECT or FILE:
36
37         Either  a file path or a persistent handle value to save the endorse‐
38         ment key.
39
40         If a value of - is passed the tool will find a vacant persistent han‐
41         dle to use and print out the automatically selected handle.
42
43         If  one saves the context file via this option and the public key via
44         the -u option, the EK can be restored via a call  to  tpm2_loadexter‐
45         nal(1).
46
47       · -G, --key-algorithm=ALGORITHM:
48         The endorsement key algorithm.  Supports:
49
50         · ecc - An P256 key.
51
52         · rsa - An RSA2048 key.
53
54         · keyedhash - hmac key.
55
56       · -u, --public=FILE:
57
58         The  optional input for a file to save the public portion of endorse‐
59         ment key.
60
61       · -t, --template=FILE:
62
63         The optional manufacturer defined endorsement key template and  nonce
64         from  fixed NV Indices to populate the TPM2B_PUBLIC public area.  See
65         the TCG EK Credential Profile  specification  for  more  information:
66         https://trustedcomputinggroup.org/wp-content/uploads/ TCG_IWG_Creden‐
67         tial_Profile_EK_V2.1_R13.pdf
68
69       · -f, --format=FORMAT:
70
71         Public key format.
72
73   References

Context Object Format

75       The type of a context object, whether it is a handle or file  name,  is
76       determined according to the following logic in-order:
77
78       · If the argument is a file path, then the file is loaded as a restored
79         TPM transient object.
80
81       · If the argument is a prefix match on one of:
82
83         · owner: the owner hierarchy
84
85         · platform: the platform hierarchy
86
87         · endorsement: the endorsement hierarchy
88
89         · lockout: the lockout control persistent object
90
91       · If the argument argument can be loaded as a number it will  be  treat
92         as a handle, e.g.  0x81010013 and used directly.OBJECT.
93

Authorization Formatting

95       Authorization  for  use  of an object in TPM2.0 can come in 3 different
96       forms: 1.  Password 2.  HMAC 3.  Sessions
97
98       NOTE: "Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
99       fied".
100
101   Passwords
102       Passwords  are  interpreted  in  the following forms below using prefix
103       identifiers.
104
105       Note: By default passwords are assumed to be in the  string  form  when
106       they do not have a prefix.
107
108   String
109       A  string  password,  specified  by  prefix "str:" or it's absence (raw
110       string without prefix) is not interpreted, and is directly used for au‐
111       thorization.
112
113   Examples
114              foobar
115              str:foobar
116
117   Hex-string
118       A  hex-string  password, specified by prefix "hex:" is converted from a
119       hexidecimal form into a byte array form, thus allowing  passwords  with
120       non-printable and/or terminal un-friendly characters.
121
122   Example
123              hex:0x1122334455667788
124
125   File
126       A  file  based password, specified be prefix "file:" should be the path
127       of a file containing the password to be read by the tool or  a  "-"  to
128       use  stdin.   Storing  passwords in files prevents information leakage,
129       passwords passed as options can be read from the process list or common
130       shell history features.
131
132   Examples
133              # to use stdin and be prompted
134              file:-
135
136              # to use a file from a path
137              file:path/to/password/file
138
139              # to echo a password via stdin:
140              echo foobar | tpm2_tool -p file:-
141
142              # to use a bash here-string via stdin:
143
144              tpm2_tool -p file:- <<< foobar
145
146   Sessions
147       When  using  a policy session to authorize the use of an object, prefix
148       the option argument with the session keyword.  Then indicate a path  to
149       a session file that was created with tpm2_startauthsession(1).  Option‐
150       ally, if the session requires an auth value to be sent with the session
151       handle  (eg policy password), then append a + and a string as described
152       in the Passwords section.
153
154   Examples
155       To use a session context file called session.ctx.
156
157              session:session.ctx
158
159       To use a session context file called session.ctx AND send the authvalue
160       mypassword.
161
162              session:session.ctx+mypassword
163
164       To use a session context file called session.ctx AND send the HEX auth‐
165       value 0x11223344.
166
167              session:session.ctx+hex:11223344
168
169   PCR Authorizations
170       You can satisfy a PCR policy using the "pcr:" prefix and the PCR  mini‐
171       language.       The     PCR     minilanguage     is     as     follows:
172       <pcr-spec>=<raw-pcr-file>
173
174       The PCR spec is documented in in the section "PCR bank specifiers".
175
176       The raw-pcr-file is an optional the output of the raw PCR  contents  as
177       returned by tpm2_pcrread(1).
178
179       PCR bank specifiers (common/pcr.md)
180
181   Examples
182       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
183       er of:
184
185              pcr:sha256:0,1,2,3
186
187       specifying AUTH.
188

Algorithm Specifiers

190       Options that take algorithms support "nice-names".
191
192       There are two major algorithm specification string classes, simple  and
193       complex.  Only certain algorithms will be accepted by the TPM, based on
194       usage and conditions.
195
196   Simple specifiers
197       These are strings with no additional specification data.  When creating
198       objects,  non-specified  portions of an object are assumed to defaults.
199       You can find the list of known "Simple Specifiers Below".
200
201   Asymmetric
202       · rsa
203
204       · ecc
205
206   Symmetric
207       · aes
208
209       · camellia
210
211   Hashing Algorithms
212       · sha1
213
214       · sha256
215
216       · sha384
217
218       · sha512
219
220       · sm3_256
221
222       · sha3_256
223
224       · sha3_384
225
226       · sha3_512
227
228   Keyed Hash
229       · hmac
230
231       · xor
232
233   Signing Schemes
234       · rsassa
235
236       · rsapss
237
238       · ecdsa
239
240       · ecdaa
241
242       · ecschnorr
243
244   Asymmetric Encryption Schemes
245       · oaep
246
247       · rsaes
248
249       · ecdh
250
251   Modes
252       · ctr
253
254       · ofb
255
256       · cbc
257
258       · cfb
259
260       · ecb
261
262   Misc
263       · null
264
265   Complex Specifiers
266       Objects, when specified for creation by the TPM,  have  numerous  algo‐
267       rithms  to  populate  in the public data.  Things like type, scheme and
268       asymmetric details, key size, etc.  Below is  the  general  format  for
269       specifying this data: <type>:<scheme>:<symmetric-details>
270
271   Type Specifiers
272       This  portion  of the complex algorithm specifier is required.  The re‐
273       maining scheme and symmetric details will default  based  on  the  type
274       specified and the type of the object being created.
275
276       · aes - Default AES: aes128
277
278       · aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
279         If mode is not specified, defaults to null.
280
281       · aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
282
283       · aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
284
285       · ecc - Elliptical Curve, defaults to ecc256.
286
287       · ecc192 - 192 bit ECC
288
289       · ecc224 - 224 bit ECC
290
291       · ecc256 - 256 bit ECC
292
293       · ecc384 - 384 bit ECC
294
295       · ecc521 - 521 bit ECC
296
297       · rsa - Default RSA: rsa2048
298
299       · rsa1024 - RSA with 1024 bit keysize.
300
301       · rsa2048 - RSA with 2048 bit keysize.
302
303       · rsa4096 - RSA with 4096 bit keysize.
304
305   Scheme Specifiers
306       Next, is an optional field, it can be skipped.
307
308       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
309       Most signing schemes take a hash algorithm directly following the sign‐
310       ing scheme.  If the hash algorithm is missing, it defaults  to  sha256.
311       Some take no arguments, and some take multiple arguments.
312
313   Hash Optional Scheme Specifiers
314       These  scheme  specifiers are followed by a dash and a valid hash algo‐
315       rithm, For example: oaep-sha256.
316
317       · oaep
318
319       · ecdh
320
321       · rsassa
322
323       · rsapss
324
325       · ecdsa
326
327       · ecschnorr
328
329   Multiple Option Scheme Specifiers
330       This scheme specifier is followed by a count  (max  size  UINT16)  then
331       folloed  by a dash(-) and a valid hash algorithm.  * ecdaa For example,
332       ecdaa4-sha256.  If no count is specified, it defaults to 4.
333
334   No Option Scheme Specifiers
335       This scheme specifier takes NO arguments.  * rsaes
336
337   Symmetric Details Specifiers
338       This field is optional, and defaults based on the type of object  being
339       created  and it's attributes.  Generally, any valid Symmetric specifier
340       from the Type Specifiers list should work.  If not specified, an  asym‐
341       metric objects symmetric details defaults to aes128cfb.
342
343   Examples
344   Create an rsa2048 key with an rsaes asymmetric encryption scheme
345       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
346
347   Create an ecc256 key with an ecdaa signing scheme with a count of 4
348       and sha384 hash
349
350       /tpm2_create -C parent.ctx -G ecc256:ec‐
351       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
352

COMMON OPTIONS

354       This collection of options are common to many programs and provide  in‐
355       formation that many users may expect.
356
357       · -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
358         attempts to invoke the manpager for the  tool,  however,  on  failure
359         will  output  a short tool summary.  This is the same behavior if the
360         "man" option argument is specified, however if explicit "man" is  re‐
361         quested,  the  tool  will  provide errors from man on stderr.  If the
362         "no-man" option if specified, or the manpager fails,  the  short  op‐
363         tions will be output to stdout.
364
365         To  successfully use the manpages feature requires the manpages to be
366         installed or on MANPATH, See man(1) for more details.
367
368       · -v, --version: Display version information for this  tool,  supported
369         tctis and exit.
370
371       · -V,  --verbose:  Increase the information that the tool prints to the
372         console during its execution.  When using this option  the  file  and
373         line number are printed.
374
375       · -Q, --quiet: Silence normal tool output to stdout.
376
377       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
378         if an errata fixup needs to be applied to commands sent to  the  TPM.
379         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
380         formation many users may expect.
381

TCTI Configuration

383       The TCTI or "Transmission Interface"  is  the  communication  mechanism
384       with  the TPM.  TCTIs can be changed for communication with TPMs across
385       different mediums.
386
387       To control the TCTI, the tools respect:
388
389       1. The command line option -T or --tcti
390
391       2. The environment variable: TPM2TOOLS_TCTI.
392
393       Note: The command line option always overrides  the  environment  vari‐
394       able.
395
396       The current known TCTIs are:
397
398       · tabrmd      -     The     resource     manager,     called     tabrmd
399         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
400         abrmd as a tcti name are synonymous.
401
402       · mssim  - Typically used for communicating to the TPM software simula‐
403         tor.
404
405       · device - Used when talking directly to a TPM device file.
406
407       · none - Do not initalize a connection with the TPM.  Some tools  allow
408         for off-tpm options and thus support not using a TCTI.  Tools that do
409         not support it will error when attempted to be used  without  a  TCTI
410         connection.   Does  not  support ANY options and MUST BE presented as
411         the exact text of "none".
412
413       The arguments to either the command  line  option  or  the  environment
414       variable are in the form:
415
416       <tcti-name>:<tcti-option-config>
417
418       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
419       tion-config> results in the default being used for that portion respec‐
420       tively.
421
422   TCTI Defaults
423       When  a  TCTI  is not specified, the default TCTI is searched for using
424       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
425       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
426       what TCTI will be chosen as the default by using the -v option to print
427       the  version information.  The "default-tcti" key-value pair will indi‐
428       cate which of the aforementioned TCTIs is the default.
429
430   Custom TCTIs
431       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
432       tools internally use dlopen(3), and the raw tcti-name value is used for
433       the lookup.  Thus, this could be a path to the shared library, or a li‐
434       brary name as understood by dlopen(3) semantics.
435

TCTI OPTIONS

437       This collection of options are used to configure the various known TCTI
438       modules available:
439
440       · device: For the device TCTI, the TPM character device file for use by
441         the device TCTI can be specified.  The default is /dev/tpm0.
442
443         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
444         vice:/dev/tpm0"
445
446       · mssim: For the mssim TCTI, the domain name or  IP  address  and  port
447         number  used  by  the  simulator  can  be specified.  The default are
448         127.0.0.1 and 2321.
449
450         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
451         TI="mssim:host=localhost,port=2321"
452
453       · abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
454         ries of simple key value pairs separated by a  ','  character.   Each
455         key and value string are separated by a '=' character.
456
457         · TCTI abrmd supports two keys:
458
459           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
460              string).
461
462           2. 'bus_type' : The type of the dbus instance (a string) limited to
463              'session' and 'system'.
464
465         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
466         ample.FooBar:
467
468         \--tcti=tabrmd:bus_name=com.example.FooBar
469
470         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
471         sion:
472
473         \--tcti:bus_type=session
474
475         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
476         ules.
477

EXAMPLES

479   Create an Endorsement Key and make it persistent
480              tpm2_createek -P abc123 -w abc123 -p passwd -c 0x81010001 -G rsa -u ek.pub
481
482   Create a transient Endorsement Key, flush it, and reload it.
483              tpm2_createek -G rsa -u ek.pub
484
485              # Check that it is loaded in transient memory
486              tpm2_getcap handles-transient
487              - 0x80000000
488
489              # Flush the handle
490              tpm2_flushcontext 0x80000000
491
492              # Note that it is flushed
493              tpm2_getcap handles-transient
494              <null output>
495
496              # Reload it via loadexternal
497              tpm2_loadexternal -C o -u ek.pub -c ek.ctx
498
499              # Check that it is re-loaded in transient memory
500              tpm2_getcap handles-transient
501              - 0x80000000
502

Returns

504       Tools can return any of the following codes:
505
506       · 0 - Success.
507
508       · 1 - General non-specific error.
509
510       · 2 - Options handling error.
511
512       · 3 - Authentication error.
513
514       · 4 - TCTI related error.
515
516       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
517

BUGS

519       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
520

HELP

522       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
523
524
525
526tpm2-tools                                                    tpm2_createek(1)
Impressum