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

NAME

6       tpm2_evictcontrol(1)  -  Make  a transient object persistent or evict a
7       persistent object.
8

SYNOPSIS

10       tpm2_evictcontrol [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_evictcontrol(1) - Allows a transient object to be made  persistent
14       or a persistent object to be evicted.  The HANDLE argument controls the
15       index the handle will be assigned to.  If the object specified  via  -c
16       is  transient,  and a permanent HANDLE is specified, the object will be
17       persisted at HANDLE.  If HANDLE is a -, then the object  will  be  per‐
18       sisted at the first available permanent handle location.  If the object
19       specified via -c is a permanent handle, then the object will be evicted
20       from it’s permenent handle location.
21

OPTIONS

23-C, --hierarchy=OBJECT:
24         The authorization hierarchy used to authorize the commands.  Defaults
25         to the “owner” hierarchy.  Supported options are:
26
27o for TPM_RH_OWNER
28
29p for TPM_RH_PLATFORM
30
31<num> where a raw number can be used.
32
33-c, --object-context=OBJECT:
34
35         A context object specifier of a transient or persistent  object.   If
36         OBJECT is a transient object it will be persisted, either to the han‐
37         dle specified by the argument or to first available vacant persistent
38         handle.   If  the  OBJECT is for a persistent object, then the object
39         will be evicted from non-volatile memory.
40
41-P, --auth=AUTH:
42
43         The authorization value for the hierarchy specified with -C.
44
45-o, --output=FILE:
46
47         Optionally output a serialized  object  representing  the  persistent
48         handle.  If untampered, these files are safer to use then raw persis‐
49         tent handles.  A raw persistent handle should be  verified  that  the
50         object it points to is as expected.
51
52--cphash=FILE
53
54         File path to record the hash of the command parameters.  This is com‐
55         monly termed as cpHash.  NOTE: When this option is selected, The tool
56         will not actually execute the command, it simply returns a cpHash.
57
58ARGUMENT the command line argument specifies the persistent handle to
59         save the transient object to.
60

Output

62       The tool outputs a YAML compliant dictionary with the  fields:  persis‐
63       tent-handle: action: evicted|persisted
64
65       Where  persistent-handle  is  the handle the action occurred to.  Where
66       action can either be one of evicted or  persisted.   If  an  object  is
67       evicted  then the object is no longer resident at the persistent-handle
68       address within the TPM.  If an object is persisted then the  object  is
69       resident at the persistent-handle address within the TPM.
70
71   References

Context Object Format

73       The  type  of a context object, whether it is a handle or file name, is
74       determined according to the following logic in-order:
75
76       • If the argument is a file path, then the file is loaded as a restored
77         TPM transient object.
78
79       • If the argument is a prefix match on one of:
80
81         • owner: the owner hierarchy
82
83         • platform: the platform hierarchy
84
85         • endorsement: the endorsement hierarchy
86
87         • lockout: the lockout control persistent object
88
89       • If  the  argument argument can be loaded as a number it will be treat
90         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
91

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

313   To make a transient handle persistent at address 0x81010002
314              tpm2_changeauth -c o ownerauth
315              tpm2_createprimary -c primary.ctx -P ownerauth
316              tpm2_evictcontrol -C o -c primary.ctx 0x81010002 -P ownerauth
317
318   To evict a persistent handle
319              tpm2_evictcontrol -C o -c 0x81010002 -P ownerauth
320
321   To  make  a  transient handle persistent and output a serialized persistent
322       handle.
323              tpm2_evictcontrol -C o -c primary.ctx -o primary.handle -P ownerauth
324

Returns

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

BUGS

341       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
342

HELP

344       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
345
346
347
348tpm2-tools                                                tpm2_evictcontrol(1)
Impressum