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 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 • -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 or HEX_STRING:
71 The input policy file or a hex string, 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:1122334455667788
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 • sm4
314 Hashing Algorithms
316 • sha1
317 • sha256
319 • sha384
321 • sha512
323 • sm3_256
325 • sha3_256
327 • sha3_384
329 • sha3_512
331 Keyed Hash
333 • hmac
334 • xor
336 Signing Schemes
338 • rsassa
339 • rsapss
341 • ecdsa
343 • ecdaa
345 • ecschnorr
347 • sm2
349 Asymmetric Encryption Schemes
351 • oaep
352 • rsaes
354 • ecdh
356 Modes
358 • ctr
359 • ofb
361 • cbc
363 • cfb
365 • ecb
367 Misc
369 • null
370 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 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 • aes - Default AES: aes128
383 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
385 If mode is not specified, defaults to null.
386 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
388 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
390 • sm4 - Default SM4: sm4128
392 • 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 • ecc - Elliptical Curve, defaults to ecc256.
397 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
399 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
401 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
403 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
405 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
407 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
409 • rsa - Default RSA: rsa2048
411 • rsa1024 - RSA with 1024 bit keysize.
413 • rsa2048 - RSA with 2048 bit keysize.
415 • rsa3072 - RSA with 3072 bit keysize.
417 • rsa4096 - RSA with 4096 bit keysize.
419 Scheme Specifiers
421 Next, is an optional field, it can be skipped.
422 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 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 • oaep
433 • ecdh
435 • rsassa
437 • rsapss
439 • ecdsa
441 • ecschnorr
443 • sm2
445 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 No Option Scheme Specifiers
452 This scheme specifier takes NO arguments. * rsaes
453 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 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 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 <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
476 Rev-2.0-Part-2-Structures-01.38.pdf>
477 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 For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
484 and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
485 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 • -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 To successfully use the manpages feature requires the manpages to be
501 installed or on MANPATH, See man(1) for more details.
502 • -v, --version: Display version information for this tool, supported
504 tctis and exit.
505 • -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 • -Q, --quiet: Silence normal tool output to stdout.
511 • -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 To control the TCTI, the tools respect:
523 1. The command line option -T or --tcti
525 2. The environment variable: TPM2TOOLS_TCTI.
527 Note: The command line option always overrides the environment vari‐
529 able.
530 The current known TCTIs are:
532 • 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 • mssim - Typically used for communicating to the TPM software simula‐
538 tor.
539 • device - Used when talking directly to a TPM device file.
541 • 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 The arguments to either the command line option or the environment
549 variable are in the form:
550 <tcti-name>:<tcti-option-config>
552 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
579 vice:/dev/tpm0”
580 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
586 TI=“mssim:host=localhost,port=2321”
587 • 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 • TCTI abrmd supports two keys:
593 1. `bus_name' : The name of the tabrmd service on the bus (a
595 string).
596 2. `bus_type' : The type of the dbus instance (a string) limited to
598 `session' and `system'.
599 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
601 ample.FooBar:
602 \--tcti=tabrmd:bus_name=com.example.FooBar
604 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
606 sion:
607 \--tcti:bus_type=session
609 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 tpm2_createprimary -c primary.ctx
619 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 tpm2_create -C primary.ctx -u obj.pub -r obj.priv
626 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 echo "my sealed data" > seal.dat
632 tpm2_create -C primary.ctx -i seal.dat -u obj.pub -r obj.priv
633 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 tpm2_create -C primary.ctx -G ecc -u obj.pub -r obj.priv -c ecc.ctx
647 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 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 • 0 - Success.
659 • 1 - General non-specific error.
661 • 2 - Options handling error.
663 • 3 - Authentication error.
665 • 4 - TCTI related error.
667 • 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)
676tpm2-tools tpm2_create(1)