1tpm2_load(1)                General Commands Manual               tpm2_load(1)
2
3
4

NAME

6       tpm2_load(1) - Load an object into the TPM.
7

SYNOPSIS

9       tpm2_load [OPTIONS]
10

DESCRIPTION

12       tpm2_load(1)  -  Load both the private and public portions of an object
13       into the TPM or load the object in  the  TSS2-Private-Key  PEM  format.
14       This  can  be done by specifying the private as well as the public sec‐
15       tion or via a pem file using the -r option.
16
17       The tool outputs the name of the loaded object  in  a  YAML  dictionary
18       format  with  the  key name where the value for that key is the name of
19       the object in hex format, for example:
20
21              name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3
22
23       It also saves a context file for future interactions with the object.
24
25       NOTE: Both private and public portions of the tpm key  must  be  speci‐
26       fied.  The exception to this is if a TSS2-Private-Key formatted PEM ob‐
27       ject is to be loaded which does not need the public specified.
28

OPTIONS

30-C, --parent-context=OBJECT:
31
32         The parent object.
33
34-P, --auth=AUTH:
35
36         The authorization value of the parent object specified by -C.
37
38-u, --public=FILE:
39
40         A file containing the public portion of the object.
41
42-r, --private=FILE:
43
44         A file containing the sensitive portion of the object.
45
46-n, --name=FILE:
47
48         An optional file to save the name structure of the object.
49
50-c, --key-context=FILE:
51
52         The file name of the saved object context, required.
53
54--cphash=FILE
55
56         File path to record the hash of the command parameters.  This is com‐
57         monly termed as cpHash.  NOTE: When this option is selected, The tool
58         will not actually execute the command, it simply returns a cpHash.
59
60   References

Context Object Format

62       The type of a context object, whether it is a handle or file  name,  is
63       determined according to the following logic in-order:
64
65       • If the argument is a file path, then the file is loaded as a restored
66         TPM transient object.
67
68       • If the argument is a prefix match on one of:
69
70         • owner: the owner hierarchy
71
72         • platform: the platform hierarchy
73
74         • endorsement: the endorsement hierarchy
75
76         • lockout: the lockout control persistent object
77
78       • If the argument argument can be loaded as a number it will  be  treat
79         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
80

Authorization Formatting

82       Authorization  for  use  of an object in TPM2.0 can come in 3 different
83       forms: 1.  Password 2.  HMAC 3.  Sessions
84
85       NOTE: “Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
86       fied”.
87
88   Passwords
89       Passwords  are  interpreted  in  the following forms below using prefix
90       identifiers.
91
92       Note: By default passwords are assumed to be in the  string  form  when
93       they do not have a prefix.
94
95   String
96       A  string  password,  specified  by  prefix “str:” or it’s absence (raw
97       string without prefix) is not interpreted, and is directly used for au‐
98       thorization.
99
100   Examples
101              foobar
102              str:foobar
103
104   Hex-string
105       A  hex-string  password, specified by prefix “hex:” is converted from a
106       hexidecimal form into a byte array form, thus allowing  passwords  with
107       non-printable and/or terminal un-friendly characters.
108
109   Example
110              hex:1122334455667788
111
112   File
113       A  file  based password, specified be prefix “file:” should be the path
114       of a file containing the password to be read by the tool or  a  “-”  to
115       use  stdin.   Storing  passwords in files prevents information leakage,
116       passwords passed as options can be read from the process list or common
117       shell history features.
118
119   Examples
120              # to use stdin and be prompted
121              file:-
122
123              # to use a file from a path
124              file:path/to/password/file
125
126              # to echo a password via stdin:
127              echo foobar | tpm2_tool -p file:-
128
129              # to use a bash here-string via stdin:
130
131              tpm2_tool -p file:- <<< foobar
132
133   Sessions
134       When  using  a policy session to authorize the use of an object, prefix
135       the option argument with the session keyword.  Then indicate a path  to
136       a session file that was created with tpm2_startauthsession(1).  Option‐
137       ally, if the session requires an auth value to be sent with the session
138       handle  (eg policy password), then append a + and a string as described
139       in the Passwords section.
140
141   Examples
142       To use a session context file called session.ctx.
143
144              session:session.ctx
145
146       To use a session context file called session.ctx AND send the authvalue
147       mypassword.
148
149              session:session.ctx+mypassword
150
151       To use a session context file called session.ctx AND send the HEX auth‐
152       value 0x11223344.
153
154              session:session.ctx+hex:11223344
155
156   PCR Authorizations
157       You can satisfy a PCR policy using the “pcr:” prefix and the PCR  mini‐
158       language.       The     PCR     minilanguage     is     as     follows:
159       <pcr-spec>=<raw-pcr-file>
160
161       The PCR spec is documented in in the section “PCR bank specifiers”.
162
163       The raw-pcr-file is an optional argument that contains  the  output  of
164       the raw PCR contents as returned by tpm2_pcrread(1).
165
166       PCR bank specifiers (pcr.md)
167
168   Examples
169       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
170       er of:
171
172              pcr:sha256:0,1,2,3
173
174       specifying AUTH.
175

COMMON OPTIONS

177       This collection of options are common to many programs and provide  in‐
178       formation that many users may expect.
179
180-h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
181         attempts to invoke the manpager for the  tool,  however,  on  failure
182         will  output  a short tool summary.  This is the same behavior if the
183         “man” option argument is specified, however if explicit “man” is  re‐
184         quested,  the  tool  will  provide errors from man on stderr.  If the
185         “no-man” option if specified, or the manpager fails,  the  short  op‐
186         tions will be output to stdout.
187
188         To  successfully use the manpages feature requires the manpages to be
189         installed or on MANPATH, See man(1) for more details.
190
191-v, --version: Display version information for this  tool,  supported
192         tctis and exit.
193
194-V,  --verbose:  Increase the information that the tool prints to the
195         console during its execution.  When using this option  the  file  and
196         line number are printed.
197
198-Q, --quiet: Silence normal tool output to stdout.
199
200-Z, --enable-errata: Enable the application of errata fixups.  Useful
201         if an errata fixup needs to be applied to commands sent to  the  TPM.
202         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
203         formation many users may expect.
204

TCTI Configuration

206       The TCTI or “Transmission Interface”  is  the  communication  mechanism
207       with  the TPM.  TCTIs can be changed for communication with TPMs across
208       different mediums.
209
210       To control the TCTI, the tools respect:
211
212       1. The command line option -T or --tcti
213
214       2. The environment variable: TPM2TOOLS_TCTI.
215
216       Note: The command line option always overrides  the  environment  vari‐
217       able.
218
219       The current known TCTIs are:
220
221       • tabrmd      -     The     resource     manager,     called     tabrmd
222         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
223         abrmd as a tcti name are synonymous.
224
225       • mssim  - Typically used for communicating to the TPM software simula‐
226         tor.
227
228       • device - Used when talking directly to a TPM device file.
229
230       • none - Do not initalize a connection with the TPM.  Some tools  allow
231         for off-tpm options and thus support not using a TCTI.  Tools that do
232         not support it will error when attempted to be used  without  a  TCTI
233         connection.   Does  not  support ANY options and MUST BE presented as
234         the exact text of “none”.
235
236       The arguments to either the command  line  option  or  the  environment
237       variable are in the form:
238
239       <tcti-name>:<tcti-option-config>
240
241       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
242       tion-config> results in the default being used for that portion respec‐
243       tively.
244
245   TCTI Defaults
246       When  a  TCTI  is not specified, the default TCTI is searched for using
247       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
248       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
249       what TCTI will be chosen as the default by using the -v option to print
250       the  version information.  The “default-tcti” key-value pair will indi‐
251       cate which of the aforementioned TCTIs is the default.
252
253   Custom TCTIs
254       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
255       tools internally use dlopen(3), and the raw tcti-name value is used for
256       the lookup.  Thus, this could be a path to the shared library, or a li‐
257       brary name as understood by dlopen(3) semantics.
258

TCTI OPTIONS

260       This collection of options are used to configure the various known TCTI
261       modules available:
262
263device: For the device TCTI, the TPM character device file for use by
264         the device TCTI can be specified.  The default is /dev/tpm0.
265
266         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
267         vice:/dev/tpm0”
268
269mssim: For the mssim TCTI, the domain name or  IP  address  and  port
270         number  used  by  the  simulator  can  be specified.  The default are
271         127.0.0.1 and 2321.
272
273         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
274         TI=“mssim:host=localhost,port=2321”
275
276abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
277         ries of simple key value pairs separated by a  `,'  character.   Each
278         key and value string are separated by a `=' character.
279
280         • TCTI abrmd supports two keys:
281
282           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
283              string).
284
285           2. `bus_type' : The type of the dbus instance (a string) limited to
286              `session' and `system'.
287
288         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
289         ample.FooBar:
290
291                \--tcti=tabrmd:bus_name=com.example.FooBar
292
293         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
294         sion:
295
296                \--tcti:bus_type=session
297
298         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
299         ules.
300

EXAMPLES

302   Setup
303       To load an object you first must create an object under a  primary  ob‐
304       ject.  So the first step is to create the primary object.
305
306              tpm2_createprimary -c primary.ctx
307
308       Step 2 is to create an object under the primary object.
309
310              tpm2_create -C primary.ctx -u key.pub -r key.priv
311
312       This  creates  the private and public portions of the TPM object.  With
313       these object portions, it is now possible to load that object into  the
314       TPM for subsequent use.
315
316   Loading an Object into the TPM
317       The  final  step, is loading the public and private portions of the ob‐
318       ject into the TPM.
319
320              tpm2_load  -C primary.ctx -u key.pub -r key.priv -c key.ctx
321              name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3
322

Returns

324       Tools can return any of the following codes:
325
326       • 0 - Success.
327
328       • 1 - General non-specific error.
329
330       • 2 - Options handling error.
331
332       • 3 - Authentication error.
333
334       • 4 - TCTI related error.
335
336       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
337

BUGS

339       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
340

HELP

342       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
343       fo/tpm2)
344
345
346
347tpm2-tools                                                        tpm2_load(1)
Impressum