1tpm2_create(1) General Commands Manual tpm2_create(1)
2
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 • -C, --parent-context=OBJECT:
21 The parent of the object to be created.
23 • -P, --parent-auth=AUTH:
25 The authorization value of the parent object specified with -C.
27 • -p, --key-auth=AUTH:
29 The authorization value for the created object.
31 • -g, --hash-algorithm=ALGORITHM:
33 The hash algorithm for generating the objects name. This is optional
35 and defaults to sha256 when not specified.
36 • -G, --key-algorithm=ALGORITHM:
38 The key algorithm associated with this object. It defaults to “rsa”
40 if not specified.
41 • -a, --attributes=ATTRIBUTES:
43 The object attributes, optional. The default for created objects is:
45 TPMA_OBJECT_SIGN_ENCRYPT|TPMA_OBJECT_DECRYPT|TPMA_OBJECT_FIXEDTPM|
47 TPMA_OBJECT_FIXEDPARENT|TPMA_OBJECT_SENSITIVEDATAORIGIN| TPMA_OB‐
48 JECT_USERWITHAUTH
49 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 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 inadvertant auth model where in user intended to enforce
61 a policy but inadvertantly created an object with empty auth which
62 can be used instead of policy authorization.
63 • -i, --sealing-input=FILE or STDIN:
65 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 • -L, --policy=FILE:
71 The input policy file, optional.
73 • -u, --public=FILE:
75 The output file which contains the public portion of the created ob‐
77 ject, optional.
78 • -r, --private=FILE:
80 The output file which contains the sensitive portion of the object,
82 optional. # Protection Details
83 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 In-depth details can be found in sections 23 of:
94 • https://trustedcomputinggroup.org/wp-content/up‐
96 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
97 Notably Figure 20, is relevant, even though it’s specifically referring
99 to duplication blobs, the process is identical.
100 If the output is from tpm2_duplicate(1), the output will be slightly
102 different, as described fully in section 23.
103 • -c, --key-context=FILE:
105 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 • --creation-data=FILE:
113 An optional file output that saves the creation data for certifica‐
115 tion.
116 • --template-data=FILE:
118 An optional file output that saves the key template data (TPM2B_PUB‐
120 LIC) to be used in tpm2_policytemplate.
121 • -t, --creation-ticket=FILE:
123 An optional file output that saves the creation ticket for certifica‐
125 tion.
126 • -d, --creation-hash=FILE:
128 An optional file output that saves the creation hash for certifica‐
130 tion.
131 • -q, --outside-info=HEX_STR_OR_FILE:
133 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 • -l, --pcr-list=PCR:
139 The list of PCR banks and selected PCRs’ ids for each bank to be in‐
141 cluded in the creation data for certification.
142 • --cphash=FILE
144 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 • --rphash=FILE
150 File path to record the hash of the response parameters. This is
152 commonly termed as rpHash.
153 • -S, --session=FILE:
155 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 • -f, --format:
161 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 Public key format.
170 • -o, --output=FILE:
172 The output file path, recording the public portion of the object.
174 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 • If the argument is a file path, then the file is loaded as a restored
181 TPM transient object.
182 • If the argument is a prefix match on one of:
184 • owner: the owner hierarchy
186 • platform: the platform hierarchy
188 • endorsement: the endorsement hierarchy
190 • lockout: the lockout control persistent object
192 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
201 fied”.
202 Passwords
204 Passwords are interpreted in the following forms below using prefix
205 identifiers.
206 Note: By default passwords are assumed to be in the string form when
208 they do not have a prefix.
209 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 Examples
216 foobar
217 str:foobar
218 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 Example
225 hex:0x1122334455667788
226 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 Examples
235 # to use stdin and be prompted
236 file:-
237 # to use a file from a path
239 file:path/to/password/file
240 # to echo a password via stdin:
242 echo foobar | tpm2_tool -p file:-
243 # to use a bash here-string via stdin:
245 tpm2_tool -p file:- <<< foobar
247 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 Examples
257 To use a session context file called session.ctx.
258 session:session.ctx
260 To use a session context file called session.ctx AND send the authvalue
262 mypassword.
263 session:session.ctx+mypassword
265 To use a session context file called session.ctx AND send the HEX auth‐
267 value 0x11223344.
268 session:session.ctx+hex:11223344
270 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 The PCR spec is documented in in the section “PCR bank specifiers”.
277 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 PCR bank specifiers (pcr.md)
282 Examples
284 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
285 er of:
286 pcr:sha256:0,1,2,3
288 specifying AUTH.
290
292 Options that take algorithms support “nice-names”.
293 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 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 Asymmetric
304 • rsa
305 • ecc
307 Symmetric
309 • aes
310 • camellia
312 Hashing Algorithms
314 • sha1
315 • sha256
317 • sha384
319 • sha512
321 • sm3_256
323 • sha3_256
325 • sha3_384
327 • sha3_512
329 Keyed Hash
331 • hmac
332 • xor
334 Signing Schemes
336 • rsassa
337 • rsapss
339 • ecdsa
341 • ecdaa
343 • ecschnorr
345 Asymmetric Encryption Schemes
347 • oaep
348 • rsaes
350 • ecdh
352 Modes
354 • ctr
355 • ofb
357 • cbc
359 • cfb
361 • ecb
363 Misc
365 • null
366 Complex Specifiers
368 Objects, when specified for creation by the TPM, have numerous algo‐
369 rithms to populate in the public data. Things like type, scheme and
370 asymmetric details, key size, etc. Below is the general format for
371 specifying this data: <type>:<scheme>:<symmetric-details>
372 Type Specifiers
374 This portion of the complex algorithm specifier is required. The re‐
375 maining scheme and symmetric details will default based on the type
376 specified and the type of the object being created.
377 • aes - Default AES: aes128
379 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
381 If mode is not specified, defaults to null.
382 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
384 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
386 • ecc - Elliptical Curve, defaults to ecc256.
388 • ecc192 - 192 bit ECC
390 • ecc224 - 224 bit ECC
392 • ecc256 - 256 bit ECC
394 • ecc384 - 384 bit ECC
396 • ecc521 - 521 bit ECC
398 • rsa - Default RSA: rsa2048
400 • rsa1024 - RSA with 1024 bit keysize.
402 • rsa2048 - RSA with 2048 bit keysize.
404 • rsa4096 - RSA with 4096 bit keysize.
406 Scheme Specifiers
408 Next, is an optional field, it can be skipped.
409 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
411 Most signing schemes take a hash algorithm directly following the sign‐
412 ing scheme. If the hash algorithm is missing, it defaults to sha256.
413 Some take no arguments, and some take multiple arguments.
414 Hash Optional Scheme Specifiers
416 These scheme specifiers are followed by a dash and a valid hash algo‐
417 rithm, For example: oaep-sha256.
418 • oaep
420 • ecdh
422 • rsassa
424 • rsapss
426 • ecdsa
428 • ecschnorr
430 Multiple Option Scheme Specifiers
432 This scheme specifier is followed by a count (max size UINT16) then
433 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
434 ecdaa4-sha256. If no count is specified, it defaults to 4.
435 No Option Scheme Specifiers
437 This scheme specifier takes NO arguments. * rsaes
438 Symmetric Details Specifiers
440 This field is optional, and defaults based on the type of object being
441 created and it’s attributes. Generally, any valid Symmetric specifier
442 from the Type Specifiers list should work. If not specified, an asym‐
443 metric objects symmetric details defaults to aes128cfb.
444 Examples
446 Create an rsa2048 key with an rsaes asymmetric encryption scheme
447 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
448 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
450 sha384 hash
451 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
452 key.priv cryptographic algorithms ALGORITHM.
453
455 Object Attributes are used to control various properties of created ob‐
456 jects. When specified as an option, either the raw bitfield mask or
457 “nice-names” may be used. The values can be found in Table 31 Part 2
458 of the TPM2.0 specification, which can be found here:
459 <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
461 Rev-2.0-Part-2-Structures-01.38.pdf>
462 Nice names are calculated by taking the name field of table 31 and re‐
464 moving the prefix TPMA_OBJECT_ and lowercasing the result. Thus, TP‐
465 MA_OBJECT_FIXEDTPM becomes fixedtpm. Nice names can be joined using
466 the bitwise or “|” symbol.
467 For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
469 and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
470 fixedtpm|noda|sign specifying the object attributes ATTRIBUTES.
472
474 This collection of options are common to many programs and provide in‐
475 formation that many users may expect.
476 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
478 attempts to invoke the manpager for the tool, however, on failure
479 will output a short tool summary. This is the same behavior if the
480 “man” option argument is specified, however if explicit “man” is re‐
481 quested, the tool will provide errors from man on stderr. If the
482 “no-man” option if specified, or the manpager fails, the short op‐
483 tions will be output to stdout.
484 To successfully use the manpages feature requires the manpages to be
486 installed or on MANPATH, See man(1) for more details.
487 • -v, --version: Display version information for this tool, supported
489 tctis and exit.
490 • -V, --verbose: Increase the information that the tool prints to the
492 console during its execution. When using this option the file and
493 line number are printed.
494 • -Q, --quiet: Silence normal tool output to stdout.
496 • -Z, --enable-errata: Enable the application of errata fixups. Useful
498 if an errata fixup needs to be applied to commands sent to the TPM.
499 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
500 formation many users may expect.
501
503 The TCTI or “Transmission Interface” is the communication mechanism
504 with the TPM. TCTIs can be changed for communication with TPMs across
505 different mediums.
506 To control the TCTI, the tools respect:
508 1. The command line option -T or --tcti
510 2. The environment variable: TPM2TOOLS_TCTI.
512 Note: The command line option always overrides the environment vari‐
514 able.
515 The current known TCTIs are:
517 • tabrmd - The resource manager, called tabrmd
519 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
520 abrmd as a tcti name are synonymous.
521 • mssim - Typically used for communicating to the TPM software simula‐
523 tor.
524 • device - Used when talking directly to a TPM device file.
526 • none - Do not initalize a connection with the TPM. Some tools allow
528 for off-tpm options and thus support not using a TCTI. Tools that do
529 not support it will error when attempted to be used without a TCTI
530 connection. Does not support ANY options and MUST BE presented as
531 the exact text of “none”.
532 The arguments to either the command line option or the environment
534 variable are in the form:
535 <tcti-name>:<tcti-option-config>
537 Specifying an empty string for either the <tcti-name> or <tcti-op‐
539 tion-config> results in the default being used for that portion respec‐
540 tively.
541 TCTI Defaults
543 When a TCTI is not specified, the default TCTI is searched for using
544 dlopen(3) semantics. The tools will search for tabrmd, device and
545 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
546 what TCTI will be chosen as the default by using the -v option to print
547 the version information. The “default-tcti” key-value pair will indi‐
548 cate which of the aforementioned TCTIs is the default.
549 Custom TCTIs
551 Any TCTI that implements the dynamic TCTI interface can be loaded. The
552 tools internally use dlopen(3), and the raw tcti-name value is used for
553 the lookup. Thus, this could be a path to the shared library, or a li‐
554 brary name as understood by dlopen(3) semantics.
555
557 This collection of options are used to configure the various known TCTI
558 modules available:
559 • device: For the device TCTI, the TPM character device file for use by
561 the device TCTI can be specified. The default is /dev/tpm0.
562 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
564 vice:/dev/tpm0”
565 • mssim: For the mssim TCTI, the domain name or IP address and port
567 number used by the simulator can be specified. The default are
568 127.0.0.1 and 2321.
569 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
571 TI=“mssim:host=localhost,port=2321”
572 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
574 ries of simple key value pairs separated by a `,' character. Each
575 key and value string are separated by a `=' character.
576 • TCTI abrmd supports two keys:
578 1. `bus_name' : The name of the tabrmd service on the bus (a
580 string).
581 2. `bus_type' : The type of the dbus instance (a string) limited to
583 `session' and `system'.
584 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
586 ample.FooBar:
587 \--tcti=tabrmd:bus_name=com.example.FooBar
589 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
591 sion:
592 \--tcti:bus_type=session
594 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
596 ules.
597
599 Setup
600 In order to create an object, we must first create a primary key as
601 it’s parent.
602 tpm2_createprimary -c primary.ctx
604 Create an Object
606 This will create an object using all the default values and store the
607 TPM sealed private and public portions to the paths specified via -u
608 and -r respectively. The tool defaults to an RSA key.
609 tpm2_create -C primary.ctx -u obj.pub -r obj.priv
611 Seal Data to the TPM
613 Outside of key objects, the TPM allows for small amounts of user speci‐
614 fied data to be sealed to the TPM.
615 echo "my sealed data" > seal.dat
617 tpm2_create -C primary.ctx -i seal.dat -u obj.pub -r obj.priv
618 Create an EC Key Object and Load it to the TPM
620 Normally, when creating an object, only the public and private portions
621 of the object are returned and the caller needs to use tpm2_load(1) to
622 load those public and private portions to the TPM before being able to
623 use the object. However, this can be accomplished within this command
624 as well, when supported by the TPM. You can verify your TPM supports
625 this feature by checking that tpm2_getcap(1) commands returns
626 TPM2_CC_CreateLoaded in the command set. If your TPM does not support
627 TPM2_CC_CreateLoaded an unsuported command code error will be returned.
628 If it’s not supported one must use tpm2_load(1). See that manpage for
629 details on its usage.
630 tpm2_create -C primary.ctx -G ecc -u obj.pub -r obj.priv -c ecc.ctx
632 Create an Object and get the public key as a PEM file
634 This will create an object using all the default values but also output
635 the public key as a PEM file compatible with tools like OpenSSL and
636 whatever supports PEM files.
637 tpm2_create -C primary.ctx -u obj.pub -r obj.priv -f pem -o obj.pem
639
641 Tools can return any of the following codes:
642 • 0 - Success.
644 • 1 - General non-specific error.
646 • 2 - Options handling error.
648 • 3 - Authentication error.
650 • 4 - TCTI related error.
652 • 5 - Non supported scheme. Applicable to tpm2_testparams.
654
656 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
657
659 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
660tpm2-tools tpm2_create(1)