1tpm2_evictcontrol(1) General Commands Manual tpm2_evictcontrol(1)
2
6 tpm2_evictcontrol(1) - Make a transient object persistent or evict a
7 persistent object.
8
10 tpm2_evictcontrol [OPTIONS] [ARGUMENT]
11
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
23 · -C, --hierarchy=OBJECT:
24 The authorization hierarchy used to authorize the commands. Defaults
25 to the "owner" hierarchy. Supported options are:
26 · o for TPM_RH_OWNER
28 · p for TPM_RH_PLATFORM
30 · <num> where a raw number can be used.
32 · -c, --object-context=OBJECT:
34 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 · -P, --auth=AUTH:
42 The authorization value for the hierarchy specified with -C.
44 · -o, --output=FILE:
46 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 · ARGUMENT the command line argument specifies the persistent handle to
53 save the transient object to.
54
56 The tool outputs a YAML compliant dictionary with the fields: persis‐
57 tent-handle: action: evicted|persisted
58 Where persistent-handle is the handle the action occurred to. Where
60 action can either be one of evicted or persisted. If an object is
61 evicted then the object is no longer resident at the persistent-handle
62 address within the TPM. If an object is persisted then the object is
63 resident at the persistent-handle address within the TPM.
64 References
67 The type of a context object, whether it is a handle or file name, is
68 determined according to the following logic in-order:
69 · If the argument is a file path, then the file is loaded as a restored
71 TPM transient object.
72 · If the argument is a prefix match on one of:
74 · owner: the owner hierarchy
76 · platform: the platform hierarchy
78 · endorsement: the endorsement hierarchy
80 · lockout: the lockout control persistent object
82 · If the argument argument can be loaded as a number it will be treat
84 as a handle, e.g. 0x81010013 and used directly.OBJECT.
85
87 Authorization for use of an object in TPM2.0 can come in 3 different
88 forms: 1. Password 2. HMAC 3. Sessions
89 NOTE: "Authorizations default to the EMPTY PASSWORD when not speci‐
91 fied".
92 Passwords
94 Passwords are interpreted in the following forms below using prefix
95 identifiers.
96 Note: By default passwords are assumed to be in the string form when
98 they do not have a prefix.
99 String
101 A string password, specified by prefix "str:" or it's absence (raw
102 string without prefix) is not interpreted, and is directly used for au‐
103 thorization.
104 Examples
106 foobar
107 str:foobar
108 Hex-string
110 A hex-string password, specified by prefix "hex:" is converted from a
111 hexidecimal form into a byte array form, thus allowing passwords with
112 non-printable and/or terminal un-friendly characters.
113 Example
115 hex:0x1122334455667788
116 File
118 A file based password, specified be prefix "file:" should be the path
119 of a file containing the password to be read by the tool or a "-" to
120 use stdin. Storing passwords in files prevents information leakage,
121 passwords passed as options can be read from the process list or common
122 shell history features.
123 Examples
125 # to use stdin and be prompted
126 file:-
127 # to use a file from a path
129 file:path/to/password/file
130 # to echo a password via stdin:
132 echo foobar | tpm2_tool -p file:-
133 # to use a bash here-string via stdin:
135 tpm2_tool -p file:- <<< foobar
137 Sessions
139 When using a policy session to authorize the use of an object, prefix
140 the option argument with the session keyword. Then indicate a path to
141 a session file that was created with tpm2_startauthsession(1). Option‐
142 ally, if the session requires an auth value to be sent with the session
143 handle (eg policy password), then append a + and a string as described
144 in the Passwords section.
145 Examples
147 To use a session context file called session.ctx.
148 session:session.ctx
150 To use a session context file called session.ctx AND send the authvalue
152 mypassword.
153 session:session.ctx+mypassword
155 To use a session context file called session.ctx AND send the HEX auth‐
157 value 0x11223344.
158 session:session.ctx+hex:11223344
160 PCR Authorizations
162 You can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
163 language. The PCR minilanguage is as follows:
164 <pcr-spec>=<raw-pcr-file>
165 The PCR spec is documented in in the section "PCR bank specifiers".
167 The raw-pcr-file is an optional the output of the raw PCR contents as
169 returned by tpm2_pcrread(1).
170 PCR bank specifiers (common/pcr.md)
172 Examples
174 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
175 er of:
176 pcr:sha256:0,1,2,3
178 specifying AUTH.
180
182 This collection of options are common to many programs and provide in‐
183 formation that many users may expect.
184 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
186 attempts to invoke the manpager for the tool, however, on failure
187 will output a short tool summary. This is the same behavior if the
188 "man" option argument is specified, however if explicit "man" is re‐
189 quested, the tool will provide errors from man on stderr. If the
190 "no-man" option if specified, or the manpager fails, the short op‐
191 tions will be output to stdout.
192 To successfully use the manpages feature requires the manpages to be
194 installed or on MANPATH, See man(1) for more details.
195 · -v, --version: Display version information for this tool, supported
197 tctis and exit.
198 · -V, --verbose: Increase the information that the tool prints to the
200 console during its execution. When using this option the file and
201 line number are printed.
202 · -Q, --quiet: Silence normal tool output to stdout.
204 · -Z, --enable-errata: Enable the application of errata fixups. Useful
206 if an errata fixup needs to be applied to commands sent to the TPM.
207 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
208 formation many users may expect.
209
211 The TCTI or "Transmission Interface" is the communication mechanism
212 with the TPM. TCTIs can be changed for communication with TPMs across
213 different mediums.
214 To control the TCTI, the tools respect:
216 1. The command line option -T or --tcti
218 2. The environment variable: TPM2TOOLS_TCTI.
220 Note: The command line option always overrides the environment vari‐
222 able.
223 The current known TCTIs are:
225 · tabrmd - The resource manager, called tabrmd
227 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
228 abrmd as a tcti name are synonymous.
229 · mssim - Typically used for communicating to the TPM software simula‐
231 tor.
232 · device - Used when talking directly to a TPM device file.
234 · none - Do not initalize a connection with the TPM. Some tools allow
236 for off-tpm options and thus support not using a TCTI. Tools that do
237 not support it will error when attempted to be used without a TCTI
238 connection. Does not support ANY options and MUST BE presented as
239 the exact text of "none".
240 The arguments to either the command line option or the environment
242 variable are in the form:
243 <tcti-name>:<tcti-option-config>
245 Specifying an empty string for either the <tcti-name> or <tcti-op‐
247 tion-config> results in the default being used for that portion respec‐
248 tively.
249 TCTI Defaults
251 When a TCTI is not specified, the default TCTI is searched for using
252 dlopen(3) semantics. The tools will search for tabrmd, device and
253 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
254 what TCTI will be chosen as the default by using the -v option to print
255 the version information. The "default-tcti" key-value pair will indi‐
256 cate which of the aforementioned TCTIs is the default.
257 Custom TCTIs
259 Any TCTI that implements the dynamic TCTI interface can be loaded. The
260 tools internally use dlopen(3), and the raw tcti-name value is used for
261 the lookup. Thus, this could be a path to the shared library, or a li‐
262 brary name as understood by dlopen(3) semantics.
263
265 This collection of options are used to configure the various known TCTI
266 modules available:
267 · device: For the device TCTI, the TPM character device file for use by
269 the device TCTI can be specified. The default is /dev/tpm0.
270 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
272 vice:/dev/tpm0"
273 · mssim: For the mssim TCTI, the domain name or IP address and port
275 number used by the simulator can be specified. The default are
276 127.0.0.1 and 2321.
277 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
279 TI="mssim:host=localhost,port=2321"
280 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
282 ries of simple key value pairs separated by a ',' character. Each
283 key and value string are separated by a '=' character.
284 · TCTI abrmd supports two keys:
286 1. 'bus_name' : The name of the tabrmd service on the bus (a
288 string).
289 2. 'bus_type' : The type of the dbus instance (a string) limited to
291 'session' and 'system'.
292 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
294 ample.FooBar:
295 \--tcti=tabrmd:bus_name=com.example.FooBar
297 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
299 sion:
300 \--tcti:bus_type=session
302 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
304 ules.
305
307 To make a transient handle persistent at address 0x81010002
308 tpm2_changeauth -c o ownerauth
309 tpm2_createprimary -c primary.ctx -P ownerauth
310 tpm2_evictcontrol -C o -c primary.ctx 0x81010002 -P ownerauth
311 To evict a persistent handle
313 tpm2_evictcontrol -C o -c 0x81010002 -P ownerauth
314 To make a transient handle persistent and output a serialized
316 persistent handle.
317 tpm2_evictcontrol -C o -c primary.ctx -o primary.handle -P ownerauth
319
321 Tools can return any of the following codes:
322 · 0 - Success.
324 · 1 - General non-specific error.
326 · 2 - Options handling error.
328 · 3 - Authentication error.
330 · 4 - TCTI related error.
332 · 5 - Non supported scheme. Applicable to tpm2_testparams.
334
336 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
337
339 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
340tpm2-tools tpm2_evictcontrol(1)