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 • --cphash=FILE
53 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 • ARGUMENT the command line argument specifies the persistent handle to
59 save the transient object to.
60
62 The tool outputs a YAML compliant dictionary with the fields: persis‐
63 tent-handle: action: evicted|persisted
64 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 References
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 • If the argument is a file path, then the file is loaded as a restored
77 TPM transient object.
78 • If the argument is a prefix match on one of:
80 • owner: the owner hierarchy
82 • platform: the platform hierarchy
84 • endorsement: the endorsement hierarchy
86 • lockout: the lockout control persistent object
88 • 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
93 Authorization for use of an object in TPM2.0 can come in 3 different
94 forms: 1. Password 2. HMAC 3. Sessions
95 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
97 fied”.
98 Passwords
100 Passwords are interpreted in the following forms below using prefix
101 identifiers.
102 Note: By default passwords are assumed to be in the string form when
104 they do not have a prefix.
105 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 Examples
112 foobar
113 str:foobar
114 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 Example
121 hex:1122334455667788
122 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 Examples
131 # to use stdin and be prompted
132 file:-
133 # to use a file from a path
135 file:path/to/password/file
136 # to echo a password via stdin:
138 echo foobar | tpm2_tool -p file:-
139 # to use a bash here-string via stdin:
141 tpm2_tool -p file:- <<< foobar
143 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 Examples
153 To use a session context file called session.ctx.
154 session:session.ctx
156 To use a session context file called session.ctx AND send the authvalue
158 mypassword.
159 session:session.ctx+mypassword
161 To use a session context file called session.ctx AND send the HEX auth‐
163 value 0x11223344.
164 session:session.ctx+hex:11223344
166 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 The PCR spec is documented in in the section “PCR bank specifiers”.
173 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 PCR bank specifiers (pcr.md)
178 Examples
180 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
181 er of:
182 pcr:sha256:0,1,2,3
184 specifying AUTH.
186
188 This collection of options are common to many programs and provide in‐
189 formation that many users may expect.
190 • -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 To successfully use the manpages feature requires the manpages to be
200 installed or on MANPATH, See man(1) for more details.
201 • -v, --version: Display version information for this tool, supported
203 tctis and exit.
204 • -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 • -Q, --quiet: Silence normal tool output to stdout.
210 • -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
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 To control the TCTI, the tools respect:
222 1. The command line option -T or --tcti
224 2. The environment variable: TPM2TOOLS_TCTI.
226 Note: The command line option always overrides the environment vari‐
228 able.
229 The current known TCTIs are:
231 • 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 • mssim - Typically used for communicating to the TPM software simula‐
237 tor.
238 • device - Used when talking directly to a TPM device file.
240 • 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 The arguments to either the command line option or the environment
248 variable are in the form:
249 <tcti-name>:<tcti-option-config>
251 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 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 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
271 This collection of options are used to configure the various known TCTI
272 modules available:
273 • device: 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
278 vice:/dev/tpm0”
279 • mssim: 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
285 TI=“mssim:host=localhost,port=2321”
286 • abrmd: 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 • TCTI abrmd supports two keys:
292 1. `bus_name' : The name of the tabrmd service on the bus (a
294 string).
295 2. `bus_type' : The type of the dbus instance (a string) limited to
297 `session' and `system'.
298 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
300 ample.FooBar:
301 \--tcti=tabrmd:bus_name=com.example.FooBar
303 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
305 sion:
306 \--tcti:bus_type=session
308 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
310 ules.
311
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 To evict a persistent handle
319 tpm2_evictcontrol -C o -c 0x81010002 -P ownerauth
320 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
326 Tools can return any of the following codes:
327 • 0 - Success.
329 • 1 - General non-specific error.
331 • 2 - Options handling error.
333 • 3 - Authentication error.
335 • 4 - TCTI related error.
337 • 5 - Non supported scheme. Applicable to tpm2_testparams.
339
341 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
342
344 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
345 fo/tpm2)
346tpm2-tools tpm2_evictcontrol(1)