1tpm2_duplicate(1) General Commands Manual tpm2_duplicate(1)
2
6 tpm2_duplicate(1) - Duplicates a loaded object so that it may be used
7 in a different hierarchy.
8
10 tpm2_duplicate [OPTIONS]
11
13 tpm2_duplicate(1) - This tool duplicates a loaded object so that it may
14 be used in a different hierarchy. The new parent key for the duplicate
15 may be on the same or different TPM or TPM_RH_NULL.
16
18 These options control the key importation process:
19 • -G, --wrapper-algorithm=ALGORITHM:
21 The symmetric algorithm to be used for the inner wrapper. Supports:
22 • aes - AES 128 in CFB mode.
24 • null - none
26 • -i, --encryptionkey-in=FILE:
28 Specifies the filename of the symmetric key (128 bit data) to be used
30 for the inner wrapper. Valid only when specified symmetric algorithm
31 is not null
32 • -o, --encryptionkey-out=FILE:
34 Specifies the filename to store the symmetric key (128 bit data) that
36 was used for the inner wrapper. Valid only when specified symmetric
37 algorithm is not null and --input-key-file is not specified. The TPM
38 generates the key in this case.
39 • -C, --parent-context=OBJECT:
41 The parent key object.
43 • -U, --parent-public=FILE:
45 Specifies the file path to the public key of the parent object on the
47 destination TPM. This should be a TPM2B_PUBLIC formatted file.
48 • -k, --private-key=FILE:
50 Specifies the file path to the external private key be encrypted for
52 the remote TPM. This should be a PEM format private key.
53 • -r, --private=FILE:
55 Specifies the file path to save the private portion of the duplicated
57 object. # Protection Details
58 Objects that can move outside of TPM need to be protected (confiden‐
60 tiality and integrity). For instance, transient objects require that
61 TPM protected data (key or seal material) be stored outside of the TPM.
62 This is seen in tools like tpm2_create(1), where the -r option outputs
63 this protected data. This blob contains the sensitive portions of the
64 object. The sensitive portions of the object are protected by the par‐
65 ent object, using the parent’s symmetric encryption details to encrypt
66 the sensitive data and HMAC it.
67 In-depth details can be found in sections 23 of:
69 • https://trustedcomputinggroup.org/wp-content/up‐
71 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
72 Notably Figure 20, is relevant, even though it’s specifically referring
74 to duplication blobs, the process is identical.
75 If the output is from tpm2_duplicate(1), the output will be slightly
77 different, as described fully in section 23.
78 • -u, --public=FILE:
80 Specifies the file path to save the public portion of the duplicated
82 object, if an external key is being duplicated.
83 • -s, --encrypted-seed=FILE:
85 The file to save the encrypted seed of the duplicated object.
87 • -p, --auth=AUTH:
89 The authorization value for the key, optional.
91 • -L, --policy=FILE:
93 The input policy file, optional.
95 • -c, --key-context=OBJECT:
97 The object to be duplicated.
99 • --cphash=FILE
101 File path to record the hash of the command parameters. This is com‐
103 monly termed as cpHash. NOTE: When this option is selected, The tool
104 will not actually execute the command, it simply returns a cpHash.
105 References
108 The type of a context object, whether it is a handle or file name, is
109 determined according to the following logic in-order:
110 • If the argument is a file path, then the file is loaded as a restored
112 TPM transient object.
113 • If the argument is a prefix match on one of:
115 • owner: the owner hierarchy
117 • platform: the platform hierarchy
119 • endorsement: the endorsement hierarchy
121 • lockout: the lockout control persistent object
123 • If the argument argument can be loaded as a number it will be treat
125 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
126
128 Authorization for use of an object in TPM2.0 can come in 3 different
129 forms: 1. Password 2. HMAC 3. Sessions
130 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
132 fied”.
133 Passwords
135 Passwords are interpreted in the following forms below using prefix
136 identifiers.
137 Note: By default passwords are assumed to be in the string form when
139 they do not have a prefix.
140 String
142 A string password, specified by prefix “str:” or it’s absence (raw
143 string without prefix) is not interpreted, and is directly used for au‐
144 thorization.
145 Examples
147 foobar
148 str:foobar
149 Hex-string
151 A hex-string password, specified by prefix “hex:” is converted from a
152 hexidecimal form into a byte array form, thus allowing passwords with
153 non-printable and/or terminal un-friendly characters.
154 Example
156 hex:0x1122334455667788
157 File
159 A file based password, specified be prefix “file:” should be the path
160 of a file containing the password to be read by the tool or a “-” to
161 use stdin. Storing passwords in files prevents information leakage,
162 passwords passed as options can be read from the process list or common
163 shell history features.
164 Examples
166 # to use stdin and be prompted
167 file:-
168 # to use a file from a path
170 file:path/to/password/file
171 # to echo a password via stdin:
173 echo foobar | tpm2_tool -p file:-
174 # to use a bash here-string via stdin:
176 tpm2_tool -p file:- <<< foobar
178 Sessions
180 When using a policy session to authorize the use of an object, prefix
181 the option argument with the session keyword. Then indicate a path to
182 a session file that was created with tpm2_startauthsession(1). Option‐
183 ally, if the session requires an auth value to be sent with the session
184 handle (eg policy password), then append a + and a string as described
185 in the Passwords section.
186 Examples
188 To use a session context file called session.ctx.
189 session:session.ctx
191 To use a session context file called session.ctx AND send the authvalue
193 mypassword.
194 session:session.ctx+mypassword
196 To use a session context file called session.ctx AND send the HEX auth‐
198 value 0x11223344.
199 session:session.ctx+hex:11223344
201 PCR Authorizations
203 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
204 language. The PCR minilanguage is as follows:
205 <pcr-spec>=<raw-pcr-file>
206 The PCR spec is documented in in the section “PCR bank specifiers”.
208 The raw-pcr-file is an optional argument that contains the output of
210 the raw PCR contents as returned by tpm2_pcrread(1).
211 PCR bank specifiers (pcr.md)
213 Examples
215 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
216 er of:
217 pcr:sha256:0,1,2,3
219 specifying AUTH.
221
223 Options that take algorithms support “nice-names”.
224 There are two major algorithm specification string classes, simple and
226 complex. Only certain algorithms will be accepted by the TPM, based on
227 usage and conditions.
228 Simple specifiers
230 These are strings with no additional specification data. When creating
231 objects, non-specified portions of an object are assumed to defaults.
232 You can find the list of known “Simple Specifiers Below”.
233 Asymmetric
235 • rsa
236 • ecc
238 Symmetric
240 • aes
241 • camellia
243 Hashing Algorithms
245 • sha1
246 • sha256
248 • sha384
250 • sha512
252 • sm3_256
254 • sha3_256
256 • sha3_384
258 • sha3_512
260 Keyed Hash
262 • hmac
263 • xor
265 Signing Schemes
267 • rsassa
268 • rsapss
270 • ecdsa
272 • ecdaa
274 • ecschnorr
276 Asymmetric Encryption Schemes
278 • oaep
279 • rsaes
281 • ecdh
283 Modes
285 • ctr
286 • ofb
288 • cbc
290 • cfb
292 • ecb
294 Misc
296 • null
297 Complex Specifiers
299 Objects, when specified for creation by the TPM, have numerous algo‐
300 rithms to populate in the public data. Things like type, scheme and
301 asymmetric details, key size, etc. Below is the general format for
302 specifying this data: <type>:<scheme>:<symmetric-details>
303 Type Specifiers
305 This portion of the complex algorithm specifier is required. The re‐
306 maining scheme and symmetric details will default based on the type
307 specified and the type of the object being created.
308 • aes - Default AES: aes128
310 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
312 If mode is not specified, defaults to null.
313 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
315 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
317 • ecc - Elliptical Curve, defaults to ecc256.
319 • ecc192 - 192 bit ECC
321 • ecc224 - 224 bit ECC
323 • ecc256 - 256 bit ECC
325 • ecc384 - 384 bit ECC
327 • ecc521 - 521 bit ECC
329 • rsa - Default RSA: rsa2048
331 • rsa1024 - RSA with 1024 bit keysize.
333 • rsa2048 - RSA with 2048 bit keysize.
335 • rsa4096 - RSA with 4096 bit keysize.
337 Scheme Specifiers
339 Next, is an optional field, it can be skipped.
340 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
342 Most signing schemes take a hash algorithm directly following the sign‐
343 ing scheme. If the hash algorithm is missing, it defaults to sha256.
344 Some take no arguments, and some take multiple arguments.
345 Hash Optional Scheme Specifiers
347 These scheme specifiers are followed by a dash and a valid hash algo‐
348 rithm, For example: oaep-sha256.
349 • oaep
351 • ecdh
353 • rsassa
355 • rsapss
357 • ecdsa
359 • ecschnorr
361 Multiple Option Scheme Specifiers
363 This scheme specifier is followed by a count (max size UINT16) then
364 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
365 ecdaa4-sha256. If no count is specified, it defaults to 4.
366 No Option Scheme Specifiers
368 This scheme specifier takes NO arguments. * rsaes
369 Symmetric Details Specifiers
371 This field is optional, and defaults based on the type of object being
372 created and it’s attributes. Generally, any valid Symmetric specifier
373 from the Type Specifiers list should work. If not specified, an asym‐
374 metric objects symmetric details defaults to aes128cfb.
375 Examples
377 Create an rsa2048 key with an rsaes asymmetric encryption scheme
378 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
379 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
381 sha384 hash
382 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
383 key.priv cryptographic algorithms ALGORITHM.
384
386 This collection of options are common to many programs and provide in‐
387 formation that many users may expect.
388 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
390 attempts to invoke the manpager for the tool, however, on failure
391 will output a short tool summary. This is the same behavior if the
392 “man” option argument is specified, however if explicit “man” is re‐
393 quested, the tool will provide errors from man on stderr. If the
394 “no-man” option if specified, or the manpager fails, the short op‐
395 tions will be output to stdout.
396 To successfully use the manpages feature requires the manpages to be
398 installed or on MANPATH, See man(1) for more details.
399 • -v, --version: Display version information for this tool, supported
401 tctis and exit.
402 • -V, --verbose: Increase the information that the tool prints to the
404 console during its execution. When using this option the file and
405 line number are printed.
406 • -Q, --quiet: Silence normal tool output to stdout.
408 • -Z, --enable-errata: Enable the application of errata fixups. Useful
410 if an errata fixup needs to be applied to commands sent to the TPM.
411 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
412 formation many users may expect.
413
415 The TCTI or “Transmission Interface” is the communication mechanism
416 with the TPM. TCTIs can be changed for communication with TPMs across
417 different mediums.
418 To control the TCTI, the tools respect:
420 1. The command line option -T or --tcti
422 2. The environment variable: TPM2TOOLS_TCTI.
424 Note: The command line option always overrides the environment vari‐
426 able.
427 The current known TCTIs are:
429 • tabrmd - The resource manager, called tabrmd
431 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
432 abrmd as a tcti name are synonymous.
433 • mssim - Typically used for communicating to the TPM software simula‐
435 tor.
436 • device - Used when talking directly to a TPM device file.
438 • none - Do not initalize a connection with the TPM. Some tools allow
440 for off-tpm options and thus support not using a TCTI. Tools that do
441 not support it will error when attempted to be used without a TCTI
442 connection. Does not support ANY options and MUST BE presented as
443 the exact text of “none”.
444 The arguments to either the command line option or the environment
446 variable are in the form:
447 <tcti-name>:<tcti-option-config>
449 Specifying an empty string for either the <tcti-name> or <tcti-op‐
451 tion-config> results in the default being used for that portion respec‐
452 tively.
453 TCTI Defaults
455 When a TCTI is not specified, the default TCTI is searched for using
456 dlopen(3) semantics. The tools will search for tabrmd, device and
457 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
458 what TCTI will be chosen as the default by using the -v option to print
459 the version information. The “default-tcti” key-value pair will indi‐
460 cate which of the aforementioned TCTIs is the default.
461 Custom TCTIs
463 Any TCTI that implements the dynamic TCTI interface can be loaded. The
464 tools internally use dlopen(3), and the raw tcti-name value is used for
465 the lookup. Thus, this could be a path to the shared library, or a li‐
466 brary name as understood by dlopen(3) semantics.
467
469 This collection of options are used to configure the various known TCTI
470 modules available:
471 • device: For the device TCTI, the TPM character device file for use by
473 the device TCTI can be specified. The default is /dev/tpm0.
474 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
476 vice:/dev/tpm0”
477 • mssim: For the mssim TCTI, the domain name or IP address and port
479 number used by the simulator can be specified. The default are
480 127.0.0.1 and 2321.
481 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
483 TI=“mssim:host=localhost,port=2321”
484 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
486 ries of simple key value pairs separated by a `,' character. Each
487 key and value string are separated by a `=' character.
488 • TCTI abrmd supports two keys:
490 1. `bus_name' : The name of the tabrmd service on the bus (a
492 string).
493 2. `bus_type' : The type of the dbus instance (a string) limited to
495 `session' and `system'.
496 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
498 ample.FooBar:
499 \--tcti=tabrmd:bus_name=com.example.FooBar
501 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
503 sion:
504 \--tcti:bus_type=session
506 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
508 ules.
509
511 To duplicate a key, one needs the key to duplicate, created with a pol‐
512 icy that
513 allows duplication and a new parent:
514 tpm2_startauthsession -S session.dat
516 tpm2_policycommandcode -S session.dat -L policy.dat TPM2_CC_Duplicate
517 tpm2_flushcontext session.dat
518 tpm2_createprimary -C o -g sha256 -G rsa -c primary.ctxt
520 tpm2_create -C primary.ctxt -g sha256 -G rsa -r key.prv -u key.pub \
521 -L policy.dat -a "sensitivedataorigin"
522 tpm2_loadexternal -C o -u new_parent.pub -c new_parent.ctxt
524 tpm2_startauthsession \--policy-session -S session.dat
526 tpm2_policycommandcode -S session.dat -L policy.dat TPM2_CC_Duplicate
527 tpm2_duplicate -C new_parent.ctxt -c key.ctxt -G null -p "session:session.dat" \
528 -r duprv.bin -s seed.dat
529 tpm2_flushcontext session.dat
530 As an end-to-end example, the following will transfer an RSA key gener‐
532 ated on TPM-A to TPM-B
533 On TPM-B
535 Create a parent object that will be used to wrap/transfer the key.
536 tpm2_createprimary -C o -g sha256 -G rsa -c primary.ctx
538 tpm2_create -C primary.ctx -g sha256 -G rsa \
540 -r new_parent.prv -u new_parent.pub \
541 -a "restricted|sensitivedataorigin|decrypt|userwithauth"
542 Copy new_parent.pub to TPM-A.
544 On TPM-A
546 Create root object and auth policy allows duplication only
547 tpm2_createprimary -C o -g sha256 -G rsa -c primary.ctx
549 tpm2_startauthsession -S session.dat
551 tpm2_policycommandcode -S session.dat -L dpolicy.dat TPM2_CC_Duplicate
553 tpm2_flushcontext session.dat
555 rm session.dat
557 Generate an RSA keypair on TPM-A that will be duplicated (note the
559 passphrase is `foo')
560 tpm2_create -C primary.ctx -g sha256 -G rsa -p foo -r key.prv \
562 -u key.pub -L dpolicy.dat -a "sensitivedataorigin|userwithauth|decrypt|sign"
563 tpm2_load -C primary.ctx -r key.prv -u key.pub -c key.ctx
565 tpm2_readpublic -c key.ctx -o dup.pub
567 Test sign and encryption locally (so we can compare later that the same
569 key was transferred).
570 echo "meet me at.." >file.txt
572 tpm2_rsaencrypt -c key.ctx -o data.encrypted file.txt
573 tpm2_sign -c key.ctx -g sha256 -f plain -p foo -o sign.raw file.txt
574 Compare the signature hash (we will use this later to confirm the key
576 was transferred to TPM-B):
577 sha256sum sign.raw
579 a1b4e3fbaa29e6e46d95cff498150b6b8e7d9fd21182622e8f5a3ddde257879e
581 Start an auth session and policy command to allow duplication
583 tpm2_startauthsession --policy-session -S session.dat
585 tpm2_policycommandcode -S session.dat -L dpolicy.dat TPM2_CC_Duplicate
587 Load the new_parent.pub file transferred from TPM-B
589 tpm2_loadexternal -C o -u new_parent.pub -c new_parent.ctx
591 Start the duplication
593 tpm2_duplicate -C new_parent.ctx -c key.ctx -G null \
595 -p "session:session.dat" -r dup.dpriv -s dup.seed
596 Copy the following files to TPM-B: * dup.pub * dup.dpriv * dup.seed *
598 (optionally data.encrypted just to test decryption)
599 On TPM-B
601 Start an auth,policy session
602 tpm2_startauthsession --policy-session -S session.dat
604 tpm2_policycommandcode -S session.dat -L dpolicy.dat TPM2_CC_Duplicate
606 Load the context we used to transfer
608 tpm2_flushcontext --transient-object
610 tpm2_load -C primary.ctx -u new_parent.pub -r new_parent.prv -c new_parent.ctx
612 Import the duplicated context against the parent we used
614 tpm2_import -C new_parent.ctx -u dup.pub -i dup.dpriv \
616 -r dup.prv -s dup.seed -L dpolicy.dat
617 Load the duplicated key context
619 tpm2_flushcontext --transient-object
621 tpm2_load -C new_parent.ctx -u dup.pub -r dup.prv -c dup.ctx
623 Test the imported key matches
625 • Sign
627 echo "meet me at.." >file.txt
629 tpm2_sign -c dup.ctx -g sha256 -o sig.rss -p foo file.txt
631 dd if=sig.rss of=sign.raw bs=1 skip=6 count=256
633 Compare the signature file hash:
635 $ sha256sum sign.raw
637 a1b4e3fbaa29e6e46d95cff498150b6b8e7d9fd21182622e8f5a3ddde257879e
639 • Decryption
641 tpm2_flushcontext --transient-object
643 tpm2_rsadecrypt -p foo -c dup.ctx -o data.ptext data.encrypted
645 # cat data.ptext
647 meet me at..
648 Exporting an OpenSSL RSA key for a remote TPM
650 To securely send an OpenSSL generated RSA key to a remote TPM such that
651 only that remote TPM will be able to load it, and without exposing the
652 private key to the host operating system on the remote machine:
653 • On the destination TPM-B, create a primary context and read its pub‐
655 lic key, then send primary.pub to the source machine:
656 tpm2_createprimary -c primary.ctx
658 tpm2_readpublic -c primary.ctx -o primary.pub
659 • On the source machine create the RSA private key and wrap it for the
661 destination TPM’s public key. Similar to tpm2_makecredential, this
662 step should not require a TPM.
663 openssl genrsa -out rsa.pem
665 tpm2_duplicate -U primary.pub -G rsa -k rsa.pem -u rsa.pub -r rsa.dpriv -s rsa.seed
666 • Send the rsa.pub, rsa.dpriv and rsa.seed to the destination TPM-B and
668 import the files, which will decrypt them using the primary.ctx to
669 produce rsa.priv, which can then be loaded and used as a TPM key:
670 tpm2_import -C primary.ctx -G rsa -i rsa.dpriv -s rsa.seed -u rsa.pub -r rsa.priv
672 tpm2_load -C primary.ctx -c rsa.ctx -u rsa.pub -r rsa.priv
673
675 Tools can return any of the following codes:
676 • 0 - Success.
678 • 1 - General non-specific error.
680 • 2 - Options handling error.
682 • 3 - Authentication error.
684 • 4 - TCTI related error.
686 • 5 - Non supported scheme. Applicable to tpm2_testparams.
688
690 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
691
693 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
694tpm2-tools tpm2_duplicate(1)