1tpm2_clearcontrol(1) General Commands Manual tpm2_clearcontrol(1)
2
3
4
6 tpm2_clearcontrol(1) - Set/ Clear TPMA_PERMANENT.disableClear attribute
7 to effectively block/ unblock lockout authorization handle for issuing
8 TPM clear.
9
11 tpm2_clearcontrol [OPTIONS] [ARGUMENT]
12
14 tpm2_clearcontrol(1) - Allows user with knowledge of either lockout
15 auth and or platform hierarchy auth to set disableClear which prevents
16 the lockout authorization’s capability to execute tpm2_clear. Only us‐
17 er with authorization knowledge of the platform hierarchy can clear the
18 disableClear. By default it attempts to clear the disableClear bit.
19
20 Note: Platform hierarchy auth handle can always be used to clear the
21 TPM with tpm2_clear command.
22
24 • -C, --hierarchy=OBJECT:
25
26 Specifies what auth handle, either platform hierarchy or lockout the
27 tool should operate on. By default it operates on the platform hier‐
28 archy handle. Specify the handle as p|l|platform|lockout.
29
30 NOTE : Operating on platform hierarchy require platform authentica‐
31 tion.
32
33 • -P, --auth=AUTH:
34
35 The authorization value of the hierarchy specified with -C. This
36 tool only respects the Password and HMAC options.
37
38 • --cphash=FILE
39
40 File path to record the hash of the command parameters. This is com‐
41 monly termed as cpHash. NOTE: When this option is selected, The tool
42 will not actually execute the command, it simply returns a cpHash.
43
44 • ARGUMENT ** Specify an integer 0|1 or string c|s to clear or set the
45 disableClear attribute.
46
47 References
49 The type of a context object, whether it is a handle or file name, is
50 determined according to the following logic in-order:
51
52 • If the argument is a file path, then the file is loaded as a restored
53 TPM transient object.
54
55 • If the argument is a prefix match on one of:
56
57 • owner: the owner hierarchy
58
59 • platform: the platform hierarchy
60
61 • endorsement: the endorsement hierarchy
62
63 • lockout: the lockout control persistent object
64
65 • If the argument argument can be loaded as a number it will be treat
66 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
67
69 Authorization for use of an object in TPM2.0 can come in 3 different
70 forms: 1. Password 2. HMAC 3. Sessions
71
72 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
73 fied”.
74
75 Passwords
76 Passwords are interpreted in the following forms below using prefix
77 identifiers.
78
79 Note: By default passwords are assumed to be in the string form when
80 they do not have a prefix.
81
82 String
83 A string password, specified by prefix “str:” or it’s absence (raw
84 string without prefix) is not interpreted, and is directly used for au‐
85 thorization.
86
87 Examples
88 foobar
89 str:foobar
90
91 Hex-string
92 A hex-string password, specified by prefix “hex:” is converted from a
93 hexidecimal form into a byte array form, thus allowing passwords with
94 non-printable and/or terminal un-friendly characters.
95
96 Example
97 hex:0x1122334455667788
98
99 File
100 A file based password, specified be prefix “file:” should be the path
101 of a file containing the password to be read by the tool or a “-” to
102 use stdin. Storing passwords in files prevents information leakage,
103 passwords passed as options can be read from the process list or common
104 shell history features.
105
106 Examples
107 # to use stdin and be prompted
108 file:-
109
110 # to use a file from a path
111 file:path/to/password/file
112
113 # to echo a password via stdin:
114 echo foobar | tpm2_tool -p file:-
115
116 # to use a bash here-string via stdin:
117
118 tpm2_tool -p file:- <<< foobar
119
120 Sessions
121 When using a policy session to authorize the use of an object, prefix
122 the option argument with the session keyword. Then indicate a path to
123 a session file that was created with tpm2_startauthsession(1). Option‐
124 ally, if the session requires an auth value to be sent with the session
125 handle (eg policy password), then append a + and a string as described
126 in the Passwords section.
127
128 Examples
129 To use a session context file called session.ctx.
130
131 session:session.ctx
132
133 To use a session context file called session.ctx AND send the authvalue
134 mypassword.
135
136 session:session.ctx+mypassword
137
138 To use a session context file called session.ctx AND send the HEX auth‐
139 value 0x11223344.
140
141 session:session.ctx+hex:11223344
142
143 PCR Authorizations
144 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
145 language. The PCR minilanguage is as follows:
146 <pcr-spec>=<raw-pcr-file>
147
148 The PCR spec is documented in in the section “PCR bank specifiers”.
149
150 The raw-pcr-file is an optional argument that contains the output of
151 the raw PCR contents as returned by tpm2_pcrread(1).
152
153 PCR bank specifiers (pcr.md)
154
155 Examples
156 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
157 er of:
158
159 pcr:sha256:0,1,2,3
160
161 specifying AUTH.
162
164 This collection of options are common to many programs and provide in‐
165 formation that many users may expect.
166
167 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
168 attempts to invoke the manpager for the tool, however, on failure
169 will output a short tool summary. This is the same behavior if the
170 “man” option argument is specified, however if explicit “man” is re‐
171 quested, the tool will provide errors from man on stderr. If the
172 “no-man” option if specified, or the manpager fails, the short op‐
173 tions will be output to stdout.
174
175 To successfully use the manpages feature requires the manpages to be
176 installed or on MANPATH, See man(1) for more details.
177
178 • -v, --version: Display version information for this tool, supported
179 tctis and exit.
180
181 • -V, --verbose: Increase the information that the tool prints to the
182 console during its execution. When using this option the file and
183 line number are printed.
184
185 • -Q, --quiet: Silence normal tool output to stdout.
186
187 • -Z, --enable-errata: Enable the application of errata fixups. Useful
188 if an errata fixup needs to be applied to commands sent to the TPM.
189 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
190 formation many users may expect.
191
193 The TCTI or “Transmission Interface” is the communication mechanism
194 with the TPM. TCTIs can be changed for communication with TPMs across
195 different mediums.
196
197 To control the TCTI, the tools respect:
198
199 1. The command line option -T or --tcti
200
201 2. The environment variable: TPM2TOOLS_TCTI.
202
203 Note: The command line option always overrides the environment vari‐
204 able.
205
206 The current known TCTIs are:
207
208 • tabrmd - The resource manager, called tabrmd
209 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
210 abrmd as a tcti name are synonymous.
211
212 • mssim - Typically used for communicating to the TPM software simula‐
213 tor.
214
215 • device - Used when talking directly to a TPM device file.
216
217 • none - Do not initalize a connection with the TPM. Some tools allow
218 for off-tpm options and thus support not using a TCTI. Tools that do
219 not support it will error when attempted to be used without a TCTI
220 connection. Does not support ANY options and MUST BE presented as
221 the exact text of “none”.
222
223 The arguments to either the command line option or the environment
224 variable are in the form:
225
226 <tcti-name>:<tcti-option-config>
227
228 Specifying an empty string for either the <tcti-name> or <tcti-op‐
229 tion-config> results in the default being used for that portion respec‐
230 tively.
231
232 TCTI Defaults
233 When a TCTI is not specified, the default TCTI is searched for using
234 dlopen(3) semantics. The tools will search for tabrmd, device and
235 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
236 what TCTI will be chosen as the default by using the -v option to print
237 the version information. The “default-tcti” key-value pair will indi‐
238 cate which of the aforementioned TCTIs is the default.
239
240 Custom TCTIs
241 Any TCTI that implements the dynamic TCTI interface can be loaded. The
242 tools internally use dlopen(3), and the raw tcti-name value is used for
243 the lookup. Thus, this could be a path to the shared library, or a li‐
244 brary name as understood by dlopen(3) semantics.
245
247 This collection of options are used to configure the various known TCTI
248 modules available:
249
250 • device: For the device TCTI, the TPM character device file for use by
251 the device TCTI can be specified. The default is /dev/tpm0.
252
253 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
254 vice:/dev/tpm0”
255
256 • mssim: For the mssim TCTI, the domain name or IP address and port
257 number used by the simulator can be specified. The default are
258 127.0.0.1 and 2321.
259
260 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
261 TI=“mssim:host=localhost,port=2321”
262
263 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
264 ries of simple key value pairs separated by a `,' character. Each
265 key and value string are separated by a `=' character.
266
267 • TCTI abrmd supports two keys:
268
269 1. `bus_name' : The name of the tabrmd service on the bus (a
270 string).
271
272 2. `bus_type' : The type of the dbus instance (a string) limited to
273 `session' and `system'.
274
275 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
276 ample.FooBar:
277
278 \--tcti=tabrmd:bus_name=com.example.FooBar
279
280 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
281 sion:
282
283 \--tcti:bus_type=session
284
285 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
286 ules.
287
289 Set the disableClear to block the lockout authorization’s access to TPM
290 clear
291 tpm2_clearcontrol -C l s
292
293 Clear the disableClear to unblock lockout authorization for TPM clear
294 tpm2_clearcontrol -C p c
295
297 Tools can return any of the following codes:
298
299 • 0 - Success.
300
301 • 1 - General non-specific error.
302
303 • 2 - Options handling error.
304
305 • 3 - Authentication error.
306
307 • 4 - TCTI related error.
308
309 • 5 - Non supported scheme. Applicable to tpm2_testparams.
310
312 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
313
315 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
316
317
318
319tpm2-tools tpm2_clearcontrol(1)