1tpm2_create(1) General Commands Manual tpm2_create(1)
2
3
4
6 tpm2_create(1) - Create a child object.
7
9 tpm2_create [OPTIONS]
10
12 tpm2_create(1) - Create a child object. The object can either be a key
13 or a sealing object. A sealing object allows to seal user data to the
14 TPM, with a maximum size of 128 bytes. Additionally it will load the
15 created object if the -c is specified.
16
18 These options for creating the TPM entity:
19
20 • -C, --parent-context=OBJECT:
21
22 The parent of the object to be created.
23
24 • -P, --parent-auth=AUTH:
25
26 The authorization value of the parent object specified with -C.
27
28 • -p, --key-auth=AUTH:
29
30 The authorization value for the created object.
31
32 • -g, --hash-algorithm=ALGORITHM:
33
34 The hash algorithm for generating the objects name. This is optional
35 and defaults to sha256 when not specified.
36
37 • -G, --key-algorithm=ALGORITHM:
38
39 The key algorithm associated with this object. It defaults to “rsa”
40 if not specified.
41
42 • -a, --attributes=ATTRIBUTES:
43
44 The object attributes, optional. The default for created objects is:
45
46 TPMA_OBJECT_SIGN_ENCRYPT|TPMA_OBJECT_DECRYPT|TPMA_OBJECT_FIXEDTPM|
47 TPMA_OBJECT_FIXEDPARENT|TPMA_OBJECT_SENSITIVEDATAORIGIN| TPMA_OB‐
48 JECT_USERWITHAUTH
49
50 When -i is specified for sealing, TPMA_OBJECT_SIGN_ENCRYPT and TP‐
51 MA_OBJECT_DECRYPT are removed from the default attribute set. The
52 algorithm is set in a way where the the object is only good for seal‐
53 ing and unsealing. I.e. one cannot use an object for sealing and
54 cryptography operations.
55
56 When -L is specified for adding policy based authorization informa‐
57 tion AND no string password is specified, the attribute TPMA_OB‐
58 JECT_USERWITHAUTH is cleared unless an explicit choice is made by
59 setting of the attribute with -a option. This prevents creation of
60 objects with inadvertent auth model where in user intended to enforce
61 a policy but inadvertently created an object with empty auth which
62 can be used instead of policy authorization.
63
64 • -i, --sealing-input=FILE or STDIN:
65
66 The data file to be sealed, optional. If file is -, read from stdin.
67 When sealing data only the TPM_ALG_KEYEDHASH algorithm with a NULL
68 scheme is allowed. Thus, -G cannot be specified.
69
70 • -L, --policy=FILE or HEX_STRING:
71
72 The input policy file or a hex string, optional.
73
74 • -u, --public=FILE:
75
76 The output file which contains the public portion of the created ob‐
77 ject, optional.
78
79 • -r, --private=FILE:
80
81 The output file which contains the sensitive portion of the object,
82 optional. # Protection Details
83
84 Objects that can move outside of TPM need to be protected (confiden‐
85 tiality and integrity). For instance, transient objects require that
86 TPM protected data (key or seal material) be stored outside of the TPM.
87 This is seen in tools like tpm2_create(1), where the -r option outputs
88 this protected data. This blob contains the sensitive portions of the
89 object. The sensitive portions of the object are protected by the par‐
90 ent object, using the parent’s symmetric encryption details to encrypt
91 the sensitive data and HMAC it.
92
93 In-depth details can be found in sections 23 of:
94
95 • https://trustedcomputinggroup.org/wp-content/up‐
96 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
97
98 Notably Figure 20, is relevant, even though it’s specifically referring
99 to duplication blobs, the process is identical.
100
101 If the output is from tpm2_duplicate(1), the output will be slightly
102 different, as described fully in section 23.
103
104 • -c, --key-context=FILE:
105
106 The output file which contains the key context, optional. The key
107 context is analogous to the context file produced by tpm2_load(1),
108 however is generated via a tpm2_createloaded(1) command. This option
109 can be used to avoid the normal tpm2_create(1) and tpm2_load(1) com‐
110 mand sequences and do it all in one command, atomically.
111
112 • --creation-data=FILE:
113
114 An optional file output that saves the creation data for certifica‐
115 tion.
116
117 • --template-data=FILE:
118
119 An optional file output that saves the key template data (TPM2B_PUB‐
120 LIC) to be used in tpm2_policytemplate.
121
122 • -t, --creation-ticket=FILE:
123
124 An optional file output that saves the creation ticket for certifica‐
125 tion.
126
127 • -d, --creation-hash=FILE:
128
129 An optional file output that saves the creation hash for certifica‐
130 tion.
131
132 • -q, --outside-info=HEX_STR_OR_FILE:
133
134 An optional hex string or path to add unique data to the creation da‐
135 ta. Note that it does not contribute in creating statistically
136 unique object.
137
138 • -l, --pcr-list=PCR:
139
140 The list of PCR banks and selected PCRs’ ids for each bank to be in‐
141 cluded in the creation data for certification.
142
143 • --cphash=FILE
144
145 File path to record the hash of the command parameters. This is com‐
146 monly termed as cpHash. NOTE: When this option is selected, The tool
147 will not actually execute the command, it simply returns a cpHash.
148
149 • --rphash=FILE
150
151 File path to record the hash of the response parameters. This is
152 commonly termed as rpHash.
153
154 • -S, --session=FILE:
155
156 The session created using tpm2_startauthsession. Multiple of these
157 can be specified. For example, you can have one session for audit‐
158 ing and another for encryption/decryption of the parameters.
159
160 • -f, --format:
161
162 Format selection for the public key output file. `tss' (the de‐
163 fault) will output a binary blob according to the TPM 2.0 Specifi‐
164 cation. `pem' will output an OpenSSL compatible PEM encoded public
165 key. `der' will output an OpenSSL compatible DER encoded public
166 key. `tpmt' will output a binary blob of the TPMT_PUBLIC struct
167 referenced by TPM 2.0 specs.
168
169 Public key format.
170
171 • -o, --output=FILE:
172
173 The output file path, recording the public portion of the object.
174
175 References
177 The type of a context object, whether it is a handle or file name, is
178 determined according to the following logic in-order:
179
180 • If the argument is a file path, then the file is loaded as a restored
181 TPM transient object.
182
183 • If the argument is a prefix match on one of:
184
185 • owner: the owner hierarchy
186
187 • platform: the platform hierarchy
188
189 • endorsement: the endorsement hierarchy
190
191 • lockout: the lockout control persistent object
192
193 • If the argument argument can be loaded as a number it will be treat
194 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
195
197 Authorization for use of an object in TPM2.0 can come in 3 different
198 forms: 1. Password 2. HMAC 3. Sessions
199
200 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
201 fied”.
202
203 Passwords
204 Passwords are interpreted in the following forms below using prefix
205 identifiers.
206
207 Note: By default passwords are assumed to be in the string form when
208 they do not have a prefix.
209
210 String
211 A string password, specified by prefix “str:” or it’s absence (raw
212 string without prefix) is not interpreted, and is directly used for au‐
213 thorization.
214
215 Examples
216 foobar
217 str:foobar
218
219 Hex-string
220 A hex-string password, specified by prefix “hex:” is converted from a
221 hexidecimal form into a byte array form, thus allowing passwords with
222 non-printable and/or terminal un-friendly characters.
223
224 Example
225 hex:1122334455667788
226
227 File
228 A file based password, specified be prefix “file:” should be the path
229 of a file containing the password to be read by the tool or a “-” to
230 use stdin. Storing passwords in files prevents information leakage,
231 passwords passed as options can be read from the process list or common
232 shell history features.
233
234 Examples
235 # to use stdin and be prompted
236 file:-
237
238 # to use a file from a path
239 file:path/to/password/file
240
241 # to echo a password via stdin:
242 echo foobar | tpm2_tool -p file:-
243
244 # to use a bash here-string via stdin:
245
246 tpm2_tool -p file:- <<< foobar
247
248 Sessions
249 When using a policy session to authorize the use of an object, prefix
250 the option argument with the session keyword. Then indicate a path to
251 a session file that was created with tpm2_startauthsession(1). Option‐
252 ally, if the session requires an auth value to be sent with the session
253 handle (eg policy password), then append a + and a string as described
254 in the Passwords section.
255
256 Examples
257 To use a session context file called session.ctx.
258
259 session:session.ctx
260
261 To use a session context file called session.ctx AND send the authvalue
262 mypassword.
263
264 session:session.ctx+mypassword
265
266 To use a session context file called session.ctx AND send the HEX auth‐
267 value 0x11223344.
268
269 session:session.ctx+hex:11223344
270
271 PCR Authorizations
272 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
273 language. The PCR minilanguage is as follows:
274 <pcr-spec>=<raw-pcr-file>
275
276 The PCR spec is documented in in the section “PCR bank specifiers”.
277
278 The raw-pcr-file is an optional argument that contains the output of
279 the raw PCR contents as returned by tpm2_pcrread(1).
280
281 PCR bank specifiers (pcr.md)
282
283 Examples
284 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
285 er of:
286
287 pcr:sha256:0,1,2,3
288
289 specifying AUTH.
290
292 Options that take algorithms support “nice-names”.
293
294 There are two major algorithm specification string classes, simple and
295 complex. Only certain algorithms will be accepted by the TPM, based on
296 usage and conditions.
297
298 Simple specifiers
299 These are strings with no additional specification data. When creating
300 objects, non-specified portions of an object are assumed to defaults.
301 You can find the list of known “Simple Specifiers” below.
302
303 Asymmetric
304 • rsa
305
306 • ecc
307
308 Symmetric
309 • aes
310
311 • camellia
312
313 • sm4
314
315 Hashing Algorithms
316 • sha1
317
318 • sha256
319
320 • sha384
321
322 • sha512
323
324 • sm3_256
325
326 • sha3_256
327
328 • sha3_384
329
330 • sha3_512
331
332 Keyed Hash
333 • hmac
334
335 • xor
336
337 Signing Schemes
338 • rsassa
339
340 • rsapss
341
342 • ecdsa
343
344 • ecdaa
345
346 • ecschnorr
347
348 • sm2
349
350 Asymmetric Encryption Schemes
351 • oaep
352
353 • rsaes
354
355 • ecdh
356
357 Modes
358 • ctr
359
360 • ofb
361
362 • cbc
363
364 • cfb
365
366 • ecb
367
368 Misc
369 • null
370
371 Complex Specifiers
372 Objects, when specified for creation by the TPM, have numerous algo‐
373 rithms to populate in the public data. Things like type, scheme and
374 asymmetric details, key size, etc. Below is the general format for
375 specifying this data: <type>:<scheme>:<symmetric-details>
376
377 Type Specifiers
378 This portion of the complex algorithm specifier is required. The re‐
379 maining scheme and symmetric details will default based on the type
380 specified and the type of the object being created.
381
382 • aes - Default AES: aes128
383
384 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
385 If mode is not specified, defaults to null.
386
387 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
388
389 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
390
391 • sm4 - Default SM4: sm4128
392
393 • sm4128 or sm4_128 <mode> - 128 bit SM4 with optional mode
394 (ctr|ofb|cbc|cfb|ecb). If mode is not specified, defaults to null.
395
396 • ecc - Elliptical Curve, defaults to ecc256.
397
398 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
399
400 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
401
402 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
403
404 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
405
406 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
407
408 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
409
410 • rsa - Default RSA: rsa2048
411
412 • rsa1024 - RSA with 1024 bit keysize.
413
414 • rsa2048 - RSA with 2048 bit keysize.
415
416 • rsa3072 - RSA with 3072 bit keysize.
417
418 • rsa4096 - RSA with 4096 bit keysize.
419
420 Scheme Specifiers
421 Next, is an optional field, it can be skipped.
422
423 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
424 Most signing schemes take a hash algorithm directly following the sign‐
425 ing scheme. If the hash algorithm is missing, it defaults to sha256.
426 Some take no arguments, and some take multiple arguments.
427
428 Hash Optional Scheme Specifiers
429 These scheme specifiers are followed by a dash and a valid hash algo‐
430 rithm, For example: oaep-sha256.
431
432 • oaep
433
434 • ecdh
435
436 • rsassa
437
438 • rsapss
439
440 • ecdsa
441
442 • ecschnorr
443
444 • sm2
445
446 Multiple Option Scheme Specifiers
447 This scheme specifier is followed by a count (max size UINT16) then
448 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
449 ecdaa4-sha256. If no count is specified, it defaults to 4.
450
451 No Option Scheme Specifiers
452 This scheme specifier takes NO arguments. * rsaes
453
454 Symmetric Details Specifiers
455 This field is optional, and defaults based on the type of object being
456 created and it’s attributes. Generally, any valid Symmetric specifier
457 from the Type Specifiers list should work. If not specified, an asym‐
458 metric objects symmetric details defaults to aes128cfb.
459
460 Examples
461 Create an rsa2048 key with an rsaes asymmetric encryption scheme
462 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
463
464 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
465 sha384 hash
466 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
467 key.priv cryptographic algorithms ALGORITHM.
468
470 Object Attributes are used to control various properties of created ob‐
471 jects. When specified as an option, either the raw bitfield mask or
472 “nice-names” may be used. The values can be found in Table 31 Part 2
473 of the TPM2.0 specification, which can be found here:
474
475 <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
476 Rev-2.0-Part-2-Structures-01.38.pdf>
477
478 Nice names are calculated by taking the name field of table 31 and re‐
479 moving the prefix TPMA_OBJECT_ and lowercasing the result. Thus, TP‐
480 MA_OBJECT_FIXEDTPM becomes fixedtpm. Nice names can be joined using
481 the bitwise or “|” symbol.
482
483 For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
484 and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
485
486 fixedtpm|noda|sign specifying the object attributes ATTRIBUTES.
487
489 This collection of options are common to many programs and provide in‐
490 formation that many users may expect.
491
492 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
493 attempts to invoke the manpager for the tool, however, on failure
494 will output a short tool summary. This is the same behavior if the
495 “man” option argument is specified, however if explicit “man” is re‐
496 quested, the tool will provide errors from man on stderr. If the
497 “no-man” option if specified, or the manpager fails, the short op‐
498 tions will be output to stdout.
499
500 To successfully use the manpages feature requires the manpages to be
501 installed or on MANPATH, See man(1) for more details.
502
503 • -v, --version: Display version information for this tool, supported
504 tctis and exit.
505
506 • -V, --verbose: Increase the information that the tool prints to the
507 console during its execution. When using this option the file and
508 line number are printed.
509
510 • -Q, --quiet: Silence normal tool output to stdout.
511
512 • -Z, --enable-errata: Enable the application of errata fixups. Useful
513 if an errata fixup needs to be applied to commands sent to the TPM.
514 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
515 formation many users may expect.
516
518 The TCTI or “Transmission Interface” is the communication mechanism
519 with the TPM. TCTIs can be changed for communication with TPMs across
520 different mediums.
521
522 To control the TCTI, the tools respect:
523
524 1. The command line option -T or --tcti
525
526 2. The environment variable: TPM2TOOLS_TCTI.
527
528 Note: The command line option always overrides the environment vari‐
529 able.
530
531 The current known TCTIs are:
532
533 • tabrmd - The resource manager, called tabrmd
534 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
535 abrmd as a tcti name are synonymous.
536
537 • mssim - Typically used for communicating to the TPM software simula‐
538 tor.
539
540 • device - Used when talking directly to a TPM device file.
541
542 • none - Do not initalize a connection with the TPM. Some tools allow
543 for off-tpm options and thus support not using a TCTI. Tools that do
544 not support it will error when attempted to be used without a TCTI
545 connection. Does not support ANY options and MUST BE presented as
546 the exact text of “none”.
547
548 The arguments to either the command line option or the environment
549 variable are in the form:
550
551 <tcti-name>:<tcti-option-config>
552
553 Specifying an empty string for either the <tcti-name> or <tcti-op‐
554 tion-config> results in the default being used for that portion respec‐
555 tively.
556
557 TCTI Defaults
558 When a TCTI is not specified, the default TCTI is searched for using
559 dlopen(3) semantics. The tools will search for tabrmd, device and
560 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
561 what TCTI will be chosen as the default by using the -v option to print
562 the version information. The “default-tcti” key-value pair will indi‐
563 cate which of the aforementioned TCTIs is the default.
564
565 Custom TCTIs
566 Any TCTI that implements the dynamic TCTI interface can be loaded. The
567 tools internally use dlopen(3), and the raw tcti-name value is used for
568 the lookup. Thus, this could be a path to the shared library, or a li‐
569 brary name as understood by dlopen(3) semantics.
570
572 This collection of options are used to configure the various known TCTI
573 modules available:
574
575 • device: For the device TCTI, the TPM character device file for use by
576 the device TCTI can be specified. The default is /dev/tpm0.
577
578 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
579 vice:/dev/tpm0”
580
581 • mssim: For the mssim TCTI, the domain name or IP address and port
582 number used by the simulator can be specified. The default are
583 127.0.0.1 and 2321.
584
585 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
586 TI=“mssim:host=localhost,port=2321”
587
588 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
589 ries of simple key value pairs separated by a `,' character. Each
590 key and value string are separated by a `=' character.
591
592 • TCTI abrmd supports two keys:
593
594 1. `bus_name' : The name of the tabrmd service on the bus (a
595 string).
596
597 2. `bus_type' : The type of the dbus instance (a string) limited to
598 `session' and `system'.
599
600 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
601 ample.FooBar:
602
603 \--tcti=tabrmd:bus_name=com.example.FooBar
604
605 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
606 sion:
607
608 \--tcti:bus_type=session
609
610 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
611 ules.
612
614 Setup
615 In order to create an object, we must first create a primary key as
616 it’s parent.
617
618 tpm2_createprimary -c primary.ctx
619
620 Create an Object
621 This will create an object using all the default values and store the
622 TPM sealed private and public portions to the paths specified via -u
623 and -r respectively. The tool defaults to an RSA key.
624
625 tpm2_create -C primary.ctx -u obj.pub -r obj.priv
626
627 Seal Data to the TPM
628 Outside of key objects, the TPM allows for small amounts of user speci‐
629 fied data to be sealed to the TPM.
630
631 echo "my sealed data" > seal.dat
632 tpm2_create -C primary.ctx -i seal.dat -u obj.pub -r obj.priv
633
634 Create an EC Key Object and Load it to the TPM
635 Normally, when creating an object, only the public and private portions
636 of the object are returned and the caller needs to use tpm2_load(1) to
637 load those public and private portions to the TPM before being able to
638 use the object. However, this can be accomplished within this command
639 as well, when supported by the TPM. You can verify your TPM supports
640 this feature by checking that tpm2_getcap(1) commands returns
641 TPM2_CC_CreateLoaded in the command set. If your TPM does not support
642 TPM2_CC_CreateLoaded an unsuported command code error will be returned.
643 If it’s not supported one must use tpm2_load(1). See that manpage for
644 details on its usage.
645
646 tpm2_create -C primary.ctx -G ecc -u obj.pub -r obj.priv -c ecc.ctx
647
648 Create an Object and get the public key as a PEM file
649 This will create an object using all the default values but also output
650 the public key as a PEM file compatible with tools like OpenSSL and
651 whatever supports PEM files.
652
653 tpm2_create -C primary.ctx -u obj.pub -r obj.priv -f pem -o obj.pem
654
656 Tools can return any of the following codes:
657
658 • 0 - Success.
659
660 • 1 - General non-specific error.
661
662 • 2 - Options handling error.
663
664 • 3 - Authentication error.
665
666 • 4 - TCTI related error.
667
668 • 5 - Non supported scheme. Applicable to tpm2_testparams.
669
671 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
672
674 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
675 fo/tpm2)
676
677
678
679tpm2-tools tpm2_create(1)