1tpm2_loadexternal(1) General Commands Manual tpm2_loadexternal(1)
2
6 tpm2_loadexternal(1) - Load an external object into the TPM.
7
9 tpm2_loadexternal [OPTIONS]
10
12 tpm2_loadexternal(1) - This command loads an external object into the
13 TPM, forgoing TPM protections. Ie, the key material is not protected
14 by the parent object’s seed. It can also be used to load TSS2 Private
15 Keys in pem format. The command allows loading of just the public por‐
16 tion of an object or both the public and private portions of an object.
17 For TSS2 Private Keys, only the public portion of the key is loaded.
18 The tool outputs the name of the loaded object in a YAML dictionary
20 format with the key name where the value for that key is the name of
21 the object in hex format, for example:
22 name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3
24 It also saves a context file for future interactions with the object.
26
28 • -C, --hierarchy=OBJECT:
29 Hierarchy to use for the ticket, optional. Defaults to n, null.
30 Supported options are:
31 • o for the owner hierarchy.
33 • p for the platform hierarchy.
35 • e for the endorsement hierarchy.
37 • n for the null hierarchy.
39 • -G, --key-algorithm=ALGORITHM:
41 The algorithm used by the key to be imported. Supports:
42 • aes - AES 128,192 or 256 key.
44 • rsa - RSA 1024 or 2048 key.
46 • ecc - ECC NIST P192, P224, P256, P384 or P521 public and private
48 key.
49 • -u, --public=FILE:
51 The public portion of the object, this can be one of the following
52 file formats:
53 • TSS - The TSS/TPM format. For example from option -u of command
55 tpm2_create(1).
56 • RSA - OSSL PEM formats. For example public.pem from the command
58 openssl rsa -in private.pem -out public.pem -pubout
59 • ECC - OSSL PEM formats. For example public.pem from the command
61 openssl ec -in private.ecc.pem -out public.ecc.pem -pubout
62 • -r, --private=FILE:
64 The sensitive portion of the object, optional. If one wishes to use
65 the private portion of a key, this must be specified. Like option
66 -u, this command takes files in the following format:
67 • RSA - OSSL PEM formats. For example private.pem from the command
69 openssl genrsa -out private.pem 2048 Since an RSA public key can be
70 derived from the private PEM file, their is no need to specify -u
71 for the public portion.
72 • TSS2 PrivateKey PEM formats.
74 Note: The private portion does not respect TSS formats as it’s impos‐
76 sible to get a TPM2B_SENSITIVE output from a previous command. They
77 are always protected by the TPM as TPM2B_PRIVATE blobs.
78 • -p, --auth=AUTH:
80 The authorization value for the key, optional.
82 • -L, --policy=FILE or HEX_STRING:
84 The input policy file or hex string, optional. A file or hex string
86 containing the hash of a policy derived from tpm2_createpolicy or an‐
87 other policy digest generating source.
88 • -g, --hash-algorithm=ALGORITHM:
90 The hash algorithm for generating the objects name. This is optional
92 and defaults to sha256 when not specified. However, load external
93 supports having a null name algorithm. In this case, no cryptograph‐
94 ic binding checks between the public and private portions are per‐
95 formed.
96 • -a, --attributes=ATTRIBUTES:
98 The object attributes, optional. The default for created objects is:
100 TPMA_OBJECT_SIGN_ENCRYPT|TPMA_OBJECT_DECRYPT. Optionally, if -p is
101 specified or no -p or -L is specified then TPMA_OBJECT_USERWITHAUTH
102 is added to the default attribute set.
103 Note: If specifying attributes, the TPM will reject certain at‐
105 tributes like TPMA_OBJECT_FIXEDTPM, as those guarantees cannot be
106 made.
107 • -c, --key-context=FILE
109 The file name to save the object context, required.
111 • -n, --name=FILE:
113 An optional file to save the object name, which is in a binary hash
115 format. The size of the hash is based on name algorithm or the -g
116 option.
117 • --passin=OSSL_PEM_FILE_PASSWORD
119 An optional password for an Open SSL (OSSL) provided input file. It
121 mirrors the -passin option of OSSL and is known to support the pass,
122 file, env, fd and plain password formats of openssl. (see man(1)
123 openssl) for more.
124 References
127 The type of a context object, whether it is a handle or file name, is
128 determined according to the following logic in-order:
129 • If the argument is a file path, then the file is loaded as a restored
131 TPM transient object.
132 • If the argument is a prefix match on one of:
134 • owner: the owner hierarchy
136 • platform: the platform hierarchy
138 • endorsement: the endorsement hierarchy
140 • lockout: the lockout control persistent object
142 • If the argument argument can be loaded as a number it will be treat
144 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
145
147 Authorization for use of an object in TPM2.0 can come in 3 different
148 forms: 1. Password 2. HMAC 3. Sessions
149 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
151 fied”.
152 Passwords
154 Passwords are interpreted in the following forms below using prefix
155 identifiers.
156 Note: By default passwords are assumed to be in the string form when
158 they do not have a prefix.
159 String
161 A string password, specified by prefix “str:” or it’s absence (raw
162 string without prefix) is not interpreted, and is directly used for au‐
163 thorization.
164 Examples
166 foobar
167 str:foobar
168 Hex-string
170 A hex-string password, specified by prefix “hex:” is converted from a
171 hexidecimal form into a byte array form, thus allowing passwords with
172 non-printable and/or terminal un-friendly characters.
173 Example
175 hex:1122334455667788
176 File
178 A file based password, specified be prefix “file:” should be the path
179 of a file containing the password to be read by the tool or a “-” to
180 use stdin. Storing passwords in files prevents information leakage,
181 passwords passed as options can be read from the process list or common
182 shell history features.
183 Examples
185 # to use stdin and be prompted
186 file:-
187 # to use a file from a path
189 file:path/to/password/file
190 # to echo a password via stdin:
192 echo foobar | tpm2_tool -p file:-
193 # to use a bash here-string via stdin:
195 tpm2_tool -p file:- <<< foobar
197 Sessions
199 When using a policy session to authorize the use of an object, prefix
200 the option argument with the session keyword. Then indicate a path to
201 a session file that was created with tpm2_startauthsession(1). Option‐
202 ally, if the session requires an auth value to be sent with the session
203 handle (eg policy password), then append a + and a string as described
204 in the Passwords section.
205 Examples
207 To use a session context file called session.ctx.
208 session:session.ctx
210 To use a session context file called session.ctx AND send the authvalue
212 mypassword.
213 session:session.ctx+mypassword
215 To use a session context file called session.ctx AND send the HEX auth‐
217 value 0x11223344.
218 session:session.ctx+hex:11223344
220 PCR Authorizations
222 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
223 language. The PCR minilanguage is as follows:
224 <pcr-spec>=<raw-pcr-file>
225 The PCR spec is documented in in the section “PCR bank specifiers”.
227 The raw-pcr-file is an optional argument that contains the output of
229 the raw PCR contents as returned by tpm2_pcrread(1).
230 PCR bank specifiers (pcr.md)
232 Examples
234 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
235 er of:
236 pcr:sha256:0,1,2,3
238 specifying AUTH.
240
242 Options that take algorithms support “nice-names”.
243 There are two major algorithm specification string classes, simple and
245 complex. Only certain algorithms will be accepted by the TPM, based on
246 usage and conditions.
247 Simple specifiers
249 These are strings with no additional specification data. When creating
250 objects, non-specified portions of an object are assumed to defaults.
251 You can find the list of known “Simple Specifiers” below.
252 Asymmetric
254 • rsa
255 • ecc
257 Symmetric
259 • aes
260 • camellia
262 • sm4
264 Hashing Algorithms
266 • sha1
267 • sha256
269 • sha384
271 • sha512
273 • sm3_256
275 • sha3_256
277 • sha3_384
279 • sha3_512
281 Keyed Hash
283 • hmac
284 • xor
286 Signing Schemes
288 • rsassa
289 • rsapss
291 • ecdsa
293 • ecdaa
295 • ecschnorr
297 • sm2
299 Asymmetric Encryption Schemes
301 • oaep
302 • rsaes
304 • ecdh
306 Modes
308 • ctr
309 • ofb
311 • cbc
313 • cfb
315 • ecb
317 Misc
319 • null
320 Complex Specifiers
322 Objects, when specified for creation by the TPM, have numerous algo‐
323 rithms to populate in the public data. Things like type, scheme and
324 asymmetric details, key size, etc. Below is the general format for
325 specifying this data: <type>:<scheme>:<symmetric-details>
326 Type Specifiers
328 This portion of the complex algorithm specifier is required. The re‐
329 maining scheme and symmetric details will default based on the type
330 specified and the type of the object being created.
331 • aes - Default AES: aes128
333 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
335 If mode is not specified, defaults to null.
336 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
338 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
340 • sm4 - Default SM4: sm4128
342 • sm4128 or sm4_128 <mode> - 128 bit SM4 with optional mode
344 (ctr|ofb|cbc|cfb|ecb). If mode is not specified, defaults to null.
345 • ecc - Elliptical Curve, defaults to ecc256.
347 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
349 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
351 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
353 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
355 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
357 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
359 • rsa - Default RSA: rsa2048
361 • rsa1024 - RSA with 1024 bit keysize.
363 • rsa2048 - RSA with 2048 bit keysize.
365 • rsa3072 - RSA with 3072 bit keysize.
367 • rsa4096 - RSA with 4096 bit keysize.
369 Scheme Specifiers
371 Next, is an optional field, it can be skipped.
372 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
374 Most signing schemes take a hash algorithm directly following the sign‐
375 ing scheme. If the hash algorithm is missing, it defaults to sha256.
376 Some take no arguments, and some take multiple arguments.
377 Hash Optional Scheme Specifiers
379 These scheme specifiers are followed by a dash and a valid hash algo‐
380 rithm, For example: oaep-sha256.
381 • oaep
383 • ecdh
385 • rsassa
387 • rsapss
389 • ecdsa
391 • ecschnorr
393 • sm2
395 Multiple Option Scheme Specifiers
397 This scheme specifier is followed by a count (max size UINT16) then
398 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
399 ecdaa4-sha256. If no count is specified, it defaults to 4.
400 No Option Scheme Specifiers
402 This scheme specifier takes NO arguments. * rsaes
403 Symmetric Details Specifiers
405 This field is optional, and defaults based on the type of object being
406 created and it’s attributes. Generally, any valid Symmetric specifier
407 from the Type Specifiers list should work. If not specified, an asym‐
408 metric objects symmetric details defaults to aes128cfb.
409 Examples
411 Create an rsa2048 key with an rsaes asymmetric encryption scheme
412 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
413 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
415 sha384 hash
416 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
417 key.priv cryptographic algorithms ALGORITHM.
418
420 Object Attributes are used to control various properties of created ob‐
421 jects. When specified as an option, either the raw bitfield mask or
422 “nice-names” may be used. The values can be found in Table 31 Part 2
423 of the TPM2.0 specification, which can be found here:
424 <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
426 Rev-2.0-Part-2-Structures-01.38.pdf>
427 Nice names are calculated by taking the name field of table 31 and re‐
429 moving the prefix TPMA_OBJECT_ and lowercasing the result. Thus, TP‐
430 MA_OBJECT_FIXEDTPM becomes fixedtpm. Nice names can be joined using
431 the bitwise or “|” symbol.
432 For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
434 and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
435 fixedtpm|noda|sign specifying the object attributes ATTRIBUTES.
437
439 This collection of options are common to many programs and provide in‐
440 formation that many users may expect.
441 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
443 attempts to invoke the manpager for the tool, however, on failure
444 will output a short tool summary. This is the same behavior if the
445 “man” option argument is specified, however if explicit “man” is re‐
446 quested, the tool will provide errors from man on stderr. If the
447 “no-man” option if specified, or the manpager fails, the short op‐
448 tions will be output to stdout.
449 To successfully use the manpages feature requires the manpages to be
451 installed or on MANPATH, See man(1) for more details.
452 • -v, --version: Display version information for this tool, supported
454 tctis and exit.
455 • -V, --verbose: Increase the information that the tool prints to the
457 console during its execution. When using this option the file and
458 line number are printed.
459 • -Q, --quiet: Silence normal tool output to stdout.
461 • -Z, --enable-errata: Enable the application of errata fixups. Useful
463 if an errata fixup needs to be applied to commands sent to the TPM.
464 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
465 formation many users may expect.
466
468 The TCTI or “Transmission Interface” is the communication mechanism
469 with the TPM. TCTIs can be changed for communication with TPMs across
470 different mediums.
471 To control the TCTI, the tools respect:
473 1. The command line option -T or --tcti
475 2. The environment variable: TPM2TOOLS_TCTI.
477 Note: The command line option always overrides the environment vari‐
479 able.
480 The current known TCTIs are:
482 • tabrmd - The resource manager, called tabrmd
484 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
485 abrmd as a tcti name are synonymous.
486 • mssim - Typically used for communicating to the TPM software simula‐
488 tor.
489 • device - Used when talking directly to a TPM device file.
491 • none - Do not initalize a connection with the TPM. Some tools allow
493 for off-tpm options and thus support not using a TCTI. Tools that do
494 not support it will error when attempted to be used without a TCTI
495 connection. Does not support ANY options and MUST BE presented as
496 the exact text of “none”.
497 The arguments to either the command line option or the environment
499 variable are in the form:
500 <tcti-name>:<tcti-option-config>
502 Specifying an empty string for either the <tcti-name> or <tcti-op‐
504 tion-config> results in the default being used for that portion respec‐
505 tively.
506 TCTI Defaults
508 When a TCTI is not specified, the default TCTI is searched for using
509 dlopen(3) semantics. The tools will search for tabrmd, device and
510 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
511 what TCTI will be chosen as the default by using the -v option to print
512 the version information. The “default-tcti” key-value pair will indi‐
513 cate which of the aforementioned TCTIs is the default.
514 Custom TCTIs
516 Any TCTI that implements the dynamic TCTI interface can be loaded. The
517 tools internally use dlopen(3), and the raw tcti-name value is used for
518 the lookup. Thus, this could be a path to the shared library, or a li‐
519 brary name as understood by dlopen(3) semantics.
520
522 This collection of options are used to configure the various known TCTI
523 modules available:
524 • device: For the device TCTI, the TPM character device file for use by
526 the device TCTI can be specified. The default is /dev/tpm0.
527 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
529 vice:/dev/tpm0”
530 • mssim: For the mssim TCTI, the domain name or IP address and port
532 number used by the simulator can be specified. The default are
533 127.0.0.1 and 2321.
534 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
536 TI=“mssim:host=localhost,port=2321”
537 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
539 ries of simple key value pairs separated by a `,' character. Each
540 key and value string are separated by a `=' character.
541 • TCTI abrmd supports two keys:
543 1. `bus_name' : The name of the tabrmd service on the bus (a
545 string).
546 2. `bus_type' : The type of the dbus instance (a string) limited to
548 `session' and `system'.
549 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
551 ample.FooBar:
552 \--tcti=tabrmd:bus_name=com.example.FooBar
554 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
556 sion:
557 \--tcti:bus_type=session
559 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
561 ules.
562
564 • If the hierarchy is null or the name hashing algorithm is null, tick‐
565 ets produced using the object will be NULL.
566 • If the private portion of an object is specified, the hierarchy must
568 be null or the TPM will reject loading it.
569
571 Load a TPM generated public key into the owner hierarchy
572 tpm2_createprimary -c primary.ctx
573 tpm2_create -C primary.ctx -u pub.dat -r priv.dat
575 tpm2_loadexternal -C o -u pub.dat -c pub.ctx
577 name: 000b9be4d7c6193a57e1bfc86a42a6b03856a91d2f9e77c6cbdb796a783d52d4b3b9
578 Load an RSA public key into the owner hierarchy
580 openssl genrsa -out private.pem 2048
581 openssl rsa -in private.pem -out public.pem -outform PEM -pubout
583 tpm2_loadexternal -C o -Grsa -u public.pem -c key.ctx
585 name: 000b7b91d304d16995d42792b57d0fb25df7abe5fdd8afe9950730e00dc5b934ddbc
586 Load an RSA key-pair into the null hierarchy
588 openssl genrsa -out private.pem 2048
589 tpm2_loadexternal -C n -Grsa -r private.pem -c key.ctx
591 name: 000b635ea220b6c62ec1d02343859dd203c8ac5dad82ebc5b124e407d2502f88691f
592 Load an AES key into the null hierarchy
594 dd if=/dev/urandom of=sym.key bs=1 count=16
595 tpm2_loadexternal -C n -Gaes -r sym.key -c key.ctx
597 name: 000bfc4d8dd7e4f921bcc9dca4b04f49564243cd9def129a3740002bfd4b9e966d34
598 Load TSS2 Private Key into the null hierarchy
600 tpm2_loadexternal -r tss_privkey.pem -c tss_privkey.ctx
601 name: 000bc5a216702aca9ba226af1214c50dc4dc33ce6269677aa581ea6d9eec7f27000d
602
604 Tools can return any of the following codes:
605 • 0 - Success.
607 • 1 - General non-specific error.
609 • 2 - Options handling error.
611 • 3 - Authentication error.
613 • 4 - TCTI related error.
615 • 5 - Non supported scheme. Applicable to tpm2_testparams.
617
619 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
620
622 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
623 fo/tpm2)
624tpm2-tools tpm2_loadexternal(1)