1tpm2_import(1) General Commands Manual tpm2_import(1)
2
6 tpm2_import(1) - Imports an external key into the tpm as a TPM managed
7 key object.
8
10 tpm2_import [OPTIONS]
11
13 tpm2_import(1) - Imports an external generated key as TPM managed key
14 object. It requires that the parent key object be a RSA key. Can also
15 import a TPM managed key object created by the tpm2_duplicate tool.
16
18 These options control the key importation process:
19 • -G, --key-algorithm=ALGORITHM:
21 The algorithm used by the key to be imported. Supports:
22 • aes - AES 128, 192 or 256 key.
24 • rsa - RSA 1024 or 2048 key.
26 • ecc - ECC NIST P192, P224, P256, P384 or P521 public and private
28 key.
29 • -g, --hash-algorithm=ALGORITHM:
31 The hash algorithm for generating the objects name. This is optional
33 and defaults to sha256 when not specified. Algorithms should follow
34 the "formatting standards", see section "Algorithm Specifiers". Al‐
35 so, see section "Supported Hash Algorithms" for a list of supported
36 hash algorithms.
37 • -i, --input=FILE:
39 Specifies the filename of the key to be imported. For AES keys, this
41 file is the raw key bytes. For assymetric keys in PEM or DER format.
42 A typical file is generated with openssl genrsa.
43 • -C, --parent-context=OBJECT:
45 The parent key object.
47 • -U, --parent-public=FILE:
49 Optional. Specifies the parent key public data file input. This can
51 be read with tpm2_readpublic(1) tool. If not specified, the tool in‐
52 vokes a tpm2_readpublic on the parent object.
53 • -k, --encryption-key=FILE:
55 Optional. Specifies the file containing the symmetric algorithm key
57 that was used for the inner wrapper. If the file is specified the
58 tool assumes the algorithm is AES 128 in CFB mode otherwise none.
59 • -r, --private=FILE:
61 Specifies the file path required to save the encrypted private por‐
63 tion of the object imported as key.
64 When importing a duplicated object this option specifies the file
66 containing the private portion of the object to be imported. # Pro‐
67 tection Details
68 Objects that can move outside of TPM need to be protected (confiden‐
70 tiality and integrity). For instance, transient objects require that
71 TPM protected data (key or seal material) be stored outside of the TPM.
72 This is seen in tools like tpm2_create(1), where the -r option outputs
73 this protected data. This blob contains the sensitive portions of the
74 object. The sensitive portions of the object are protected by the par‐
75 ent object, using the parent's symmetric encryption details to encrypt
76 the sensitive data and HMAC it.
77 In-depth details can be found in sections 23 of:
79 • https://trustedcomputinggroup.org/wp-content/up‐
81 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
82 Notably Figure 20, is relevant, even though it's specifically referring
84 to duplication blobs, the process is identical.
85 If the output is from tpm2_duplicate(1), the output will be slightly
87 different, as described fully in section 23.
88 • -u, --public=FILE:
90 Specifies the file path required to save the public portion of the
92 object imported as key
93 When importing a duplicated object this option specifies the file
95 containing the public portion of the object to be imported.
96 • -a, --attributes=ATTRIBUTES:
98 The object attributes, optional.
100 • -P, --parent-auth=AUTH:
102 The authorization value for using the parent key specified with -C.
104 • -p, --key-auth=AUTH:
106 The authorization value for the imported key, optional.
108 • -L, --policy=POLICY_FILE:
110 The policy file.
112 • -s, --seed=FILE:
114 Specifies the file containing the encrypted seed of the duplicated
116 object.
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 • --cphash=FILE
126 File path to record the hash of the command parameters. This is com‐
128 monly termed as cpHash. NOTE: When this option is selected, The tool
129 will not actually execute the command, it simply returns a cpHash.
130 References
133 The type of a context object, whether it is a handle or file name, is
134 determined according to the following logic in-order:
135 • If the argument is a file path, then the file is loaded as a restored
137 TPM transient object.
138 • If the argument is a prefix match on one of:
140 • owner: the owner hierarchy
142 • platform: the platform hierarchy
144 • endorsement: the endorsement hierarchy
146 • lockout: the lockout control persistent object
148 • If the argument argument can be loaded as a number it will be treat
150 as a handle, e.g. 0x81010013 and used directly.OBJECT.
151
153 Authorization for use of an object in TPM2.0 can come in 3 different
154 forms: 1. Password 2. HMAC 3. Sessions
155 NOTE: "Authorizations default to the EMPTY PASSWORD when not speci‐
157 fied".
158 Passwords
160 Passwords are interpreted in the following forms below using prefix
161 identifiers.
162 Note: By default passwords are assumed to be in the string form when
164 they do not have a prefix.
165 String
167 A string password, specified by prefix "str:" or it's absence (raw
168 string without prefix) is not interpreted, and is directly used for au‐
169 thorization.
170 Examples
172 foobar
173 str:foobar
174 Hex-string
176 A hex-string password, specified by prefix "hex:" is converted from a
177 hexidecimal form into a byte array form, thus allowing passwords with
178 non-printable and/or terminal un-friendly characters.
179 Example
181 hex:0x1122334455667788
182 File
184 A file based password, specified be prefix "file:" should be the path
185 of a file containing the password to be read by the tool or a "-" to
186 use stdin. Storing passwords in files prevents information leakage,
187 passwords passed as options can be read from the process list or common
188 shell history features.
189 Examples
191 # to use stdin and be prompted
192 file:-
193 # to use a file from a path
195 file:path/to/password/file
196 # to echo a password via stdin:
198 echo foobar | tpm2_tool -p file:-
199 # to use a bash here-string via stdin:
201 tpm2_tool -p file:- <<< foobar
203 Sessions
205 When using a policy session to authorize the use of an object, prefix
206 the option argument with the session keyword. Then indicate a path to
207 a session file that was created with tpm2_startauthsession(1). Option‐
208 ally, if the session requires an auth value to be sent with the session
209 handle (eg policy password), then append a + and a string as described
210 in the Passwords section.
211 Examples
213 To use a session context file called session.ctx.
214 session:session.ctx
216 To use a session context file called session.ctx AND send the authvalue
218 mypassword.
219 session:session.ctx+mypassword
221 To use a session context file called session.ctx AND send the HEX auth‐
223 value 0x11223344.
224 session:session.ctx+hex:11223344
226 PCR Authorizations
228 You can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
229 language. The PCR minilanguage is as follows:
230 <pcr-spec>=<raw-pcr-file>
231 The PCR spec is documented in in the section "PCR bank specifiers".
233 The raw-pcr-file is an optional the output of the raw PCR contents as
235 returned by tpm2_pcrread(1).
236 PCR bank specifiers (common/pcr.md)
238 Examples
240 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
241 er of:
242 pcr:sha256:0,1,2,3
244 specifying AUTH.
246
248 Options that take algorithms support "nice-names".
249 There are two major algorithm specification string classes, simple and
251 complex. Only certain algorithms will be accepted by the TPM, based on
252 usage and conditions.
253 Simple specifiers
255 These are strings with no additional specification data. When creating
256 objects, non-specified portions of an object are assumed to defaults.
257 You can find the list of known "Simple Specifiers Below".
258 Asymmetric
260 • rsa
261 • ecc
263 Symmetric
265 • aes
266 • camellia
268 Hashing Algorithms
270 • sha1
271 • sha256
273 • sha384
275 • sha512
277 • sm3_256
279 • sha3_256
281 • sha3_384
283 • sha3_512
285 Keyed Hash
287 • hmac
288 • xor
290 Signing Schemes
292 • rsassa
293 • rsapss
295 • ecdsa
297 • ecdaa
299 • ecschnorr
301 Asymmetric Encryption Schemes
303 • oaep
304 • rsaes
306 • ecdh
308 Modes
310 • ctr
311 • ofb
313 • cbc
315 • cfb
317 • ecb
319 Misc
321 • null
322 Complex Specifiers
324 Objects, when specified for creation by the TPM, have numerous algo‐
325 rithms to populate in the public data. Things like type, scheme and
326 asymmetric details, key size, etc. Below is the general format for
327 specifying this data: <type>:<scheme>:<symmetric-details>
328 Type Specifiers
330 This portion of the complex algorithm specifier is required. The re‐
331 maining scheme and symmetric details will default based on the type
332 specified and the type of the object being created.
333 • aes - Default AES: aes128
335 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
337 If mode is not specified, defaults to null.
338 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
340 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
342 • ecc - Elliptical Curve, defaults to ecc256.
344 • ecc192 - 192 bit ECC
346 • ecc224 - 224 bit ECC
348 • ecc256 - 256 bit ECC
350 • ecc384 - 384 bit ECC
352 • ecc521 - 521 bit ECC
354 • rsa - Default RSA: rsa2048
356 • rsa1024 - RSA with 1024 bit keysize.
358 • rsa2048 - RSA with 2048 bit keysize.
360 • rsa4096 - RSA with 4096 bit keysize.
362 Scheme Specifiers
364 Next, is an optional field, it can be skipped.
365 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
367 Most signing schemes take a hash algorithm directly following the sign‐
368 ing scheme. If the hash algorithm is missing, it defaults to sha256.
369 Some take no arguments, and some take multiple arguments.
370 Hash Optional Scheme Specifiers
372 These scheme specifiers are followed by a dash and a valid hash algo‐
373 rithm, For example: oaep-sha256.
374 • oaep
376 • ecdh
378 • rsassa
380 • rsapss
382 • ecdsa
384 • ecschnorr
386 Multiple Option Scheme Specifiers
388 This scheme specifier is followed by a count (max size UINT16) then
389 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
390 ecdaa4-sha256. If no count is specified, it defaults to 4.
391 No Option Scheme Specifiers
393 This scheme specifier takes NO arguments. * rsaes
394 Symmetric Details Specifiers
396 This field is optional, and defaults based on the type of object being
397 created and it's attributes. Generally, any valid Symmetric specifier
398 from the Type Specifiers list should work. If not specified, an asym‐
399 metric objects symmetric details defaults to aes128cfb.
400 Examples
402 Create an rsa2048 key with an rsaes asymmetric encryption scheme
403 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
404 Create an ecc256 key with an ecdaa signing scheme with a count of 4
406 and sha384 hash
407 /tpm2_create -C parent.ctx -G ecc256:ec‐
409 daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
410
412 Object Attributes are used to control various properties of created ob‐
413 jects. When specified as an option, either the raw bitfield mask or
414 "nice-names" may be used. The values can be found in Table 31 Part 2
415 of the TPM2.0 specification, which can be found here:
416 <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
418 Rev-2.0-Part-2-Structures-01.38.pdf>
419 Nice names are calculated by taking the name field of table 31 and re‐
421 moving the prefix TPMA_OBJECT_ and lowercasing the result. Thus, TP‐
422 MA_OBJECT_FIXEDTPM becomes fixedtpm. Nice names can be joined using
423 the bitwise or "|" symbol.
424 For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
426 and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
427 fixedtpm|noda|sign specifying the object attributes ATTRIBUTES.
429
431 This collection of options are common to many programs and provide in‐
432 formation that many users may expect.
433 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
435 attempts to invoke the manpager for the tool, however, on failure
436 will output a short tool summary. This is the same behavior if the
437 "man" option argument is specified, however if explicit "man" is re‐
438 quested, the tool will provide errors from man on stderr. If the
439 "no-man" option if specified, or the manpager fails, the short op‐
440 tions will be output to stdout.
441 To successfully use the manpages feature requires the manpages to be
443 installed or on MANPATH, See man(1) for more details.
444 • -v, --version: Display version information for this tool, supported
446 tctis and exit.
447 • -V, --verbose: Increase the information that the tool prints to the
449 console during its execution. When using this option the file and
450 line number are printed.
451 • -Q, --quiet: Silence normal tool output to stdout.
453 • -Z, --enable-errata: Enable the application of errata fixups. Useful
455 if an errata fixup needs to be applied to commands sent to the TPM.
456 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
457 formation many users may expect.
458
460 The TCTI or "Transmission Interface" is the communication mechanism
461 with the TPM. TCTIs can be changed for communication with TPMs across
462 different mediums.
463 To control the TCTI, the tools respect:
465 1. The command line option -T or --tcti
467 2. The environment variable: TPM2TOOLS_TCTI.
469 Note: The command line option always overrides the environment vari‐
471 able.
472 The current known TCTIs are:
474 • tabrmd - The resource manager, called tabrmd
476 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
477 abrmd as a tcti name are synonymous.
478 • mssim - Typically used for communicating to the TPM software simula‐
480 tor.
481 • device - Used when talking directly to a TPM device file.
483 • none - Do not initalize a connection with the TPM. Some tools allow
485 for off-tpm options and thus support not using a TCTI. Tools that do
486 not support it will error when attempted to be used without a TCTI
487 connection. Does not support ANY options and MUST BE presented as
488 the exact text of "none".
489 The arguments to either the command line option or the environment
491 variable are in the form:
492 <tcti-name>:<tcti-option-config>
494 Specifying an empty string for either the <tcti-name> or <tcti-op‐
496 tion-config> results in the default being used for that portion respec‐
497 tively.
498 TCTI Defaults
500 When a TCTI is not specified, the default TCTI is searched for using
501 dlopen(3) semantics. The tools will search for tabrmd, device and
502 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
503 what TCTI will be chosen as the default by using the -v option to print
504 the version information. The "default-tcti" key-value pair will indi‐
505 cate which of the aforementioned TCTIs is the default.
506 Custom TCTIs
508 Any TCTI that implements the dynamic TCTI interface can be loaded. The
509 tools internally use dlopen(3), and the raw tcti-name value is used for
510 the lookup. Thus, this could be a path to the shared library, or a li‐
511 brary name as understood by dlopen(3) semantics.
512
514 This collection of options are used to configure the various known TCTI
515 modules available:
516 • device: For the device TCTI, the TPM character device file for use by
518 the device TCTI can be specified. The default is /dev/tpm0.
519 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
521 vice:/dev/tpm0"
522 • mssim: For the mssim TCTI, the domain name or IP address and port
524 number used by the simulator can be specified. The default are
525 127.0.0.1 and 2321.
526 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
528 TI="mssim:host=localhost,port=2321"
529 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
531 ries of simple key value pairs separated by a ',' character. Each
532 key and value string are separated by a '=' character.
533 • TCTI abrmd supports two keys:
535 1. 'bus_name' : The name of the tabrmd service on the bus (a
537 string).
538 2. 'bus_type' : The type of the dbus instance (a string) limited to
540 'session' and 'system'.
541 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
543 ample.FooBar:
544 \--tcti=tabrmd:bus_name=com.example.FooBar
546 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
548 sion:
549 \--tcti:bus_type=session
551 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
553 ules.
554
556 To import a key, one needs to have a parent key
557 tpm2_createprimary -Grsa2048:aes128cfb -C o -c parent.ctx
558 Create your key and and import it. If you already have a key, just use
560 that and skip creating it.
561 Import an AES 128 key
563 dd if=/dev/urandom of=sym.key bs=1 count=16
564 tpm2_import -C parent.ctx -i sym.key -u key.pub -r key.priv
566 Import an RSA key
568 openssl genrsa -out private.pem 2048
569 tpm2_import -C parent.ctx -G rsa -i private.pem -u key.pub -r key.priv
571 Import an ECC key
573 openssl ecparam -name prime256v1 -genkey -noout -out private.ecc.pem
574 tpm2_import -C parent.ctx -G ecc -i private.ecc.pem -u key.pub -r key.priv
576 Import a duplicated key
578 tpm2_import -C parent.ctx -i key.dup -u key.pub -r key.priv -L policy.dat
579
581 • The TPM requires that the name algorithm of the child be smaller than
582 the parent.
583
585 Tools can return any of the following codes:
586 • 0 - Success.
588 • 1 - General non-specific error.
590 • 2 - Options handling error.
592 • 3 - Authentication error.
594 • 4 - TCTI related error.
596 • 5 - Non supported scheme. Applicable to tpm2_testparams.
598
600 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
601
603 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
604tpm2-tools tpm2_import(1)