1tpm2_clearcontrol(1) General Commands Manual tpm2_clearcontrol(1)
2
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 Note: Platform hierarchy auth handle can always be used to clear the
21 TPM with tpm2_clear command.
22
24 • -C, --hierarchy=OBJECT:
25 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 NOTE : Operating on platform hierarchy require platform authentica‐
31 tion.
32 • -P, --auth=AUTH:
34 The authorization value of the hierarchy specified with -C. This
36 tool only respects the Password and HMAC options.
37 • --cphash=FILE
39 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 • ARGUMENT ** Specify an integer 0|1 or string c|s to clear or set the
45 disableClear attribute.
46 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 • If the argument is a file path, then the file is loaded as a restored
53 TPM transient object.
54 • If the argument is a prefix match on one of:
56 • owner: the owner hierarchy
58 • platform: the platform hierarchy
60 • endorsement: the endorsement hierarchy
62 • lockout: the lockout control persistent object
64 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
73 fied”.
74 Passwords
76 Passwords are interpreted in the following forms below using prefix
77 identifiers.
78 Note: By default passwords are assumed to be in the string form when
80 they do not have a prefix.
81 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 Examples
88 foobar
89 str:foobar
90 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 Example
97 hex:0x1122334455667788
98 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 Examples
107 # to use stdin and be prompted
108 file:-
109 # to use a file from a path
111 file:path/to/password/file
112 # to echo a password via stdin:
114 echo foobar | tpm2_tool -p file:-
115 # to use a bash here-string via stdin:
117 tpm2_tool -p file:- <<< foobar
119 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 Examples
129 To use a session context file called session.ctx.
130 session:session.ctx
132 To use a session context file called session.ctx AND send the authvalue
134 mypassword.
135 session:session.ctx+mypassword
137 To use a session context file called session.ctx AND send the HEX auth‐
139 value 0x11223344.
140 session:session.ctx+hex:11223344
142 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 The PCR spec is documented in in the section “PCR bank specifiers”.
149 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 PCR bank specifiers (pcr.md)
154 Examples
156 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
157 er of:
158 pcr:sha256:0,1,2,3
160 specifying AUTH.
162
164 This collection of options are common to many programs and provide in‐
165 formation that many users may expect.
166 • -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 To successfully use the manpages feature requires the manpages to be
176 installed or on MANPATH, See man(1) for more details.
177 • -v, --version: Display version information for this tool, supported
179 tctis and exit.
180 • -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 • -Q, --quiet: Silence normal tool output to stdout.
186 • -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 To control the TCTI, the tools respect:
198 1. The command line option -T or --tcti
200 2. The environment variable: TPM2TOOLS_TCTI.
202 Note: The command line option always overrides the environment vari‐
204 able.
205 The current known TCTIs are:
207 • 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 • mssim - Typically used for communicating to the TPM software simula‐
213 tor.
214 • device - Used when talking directly to a TPM device file.
216 • 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 The arguments to either the command line option or the environment
224 variable are in the form:
225 <tcti-name>:<tcti-option-config>
227 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
254 vice:/dev/tpm0”
255 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
261 TI=“mssim:host=localhost,port=2321”
262 • 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 • TCTI abrmd supports two keys:
268 1. `bus_name' : The name of the tabrmd service on the bus (a
270 string).
271 2. `bus_type' : The type of the dbus instance (a string) limited to
273 `session' and `system'.
274 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
276 ample.FooBar:
277 \--tcti=tabrmd:bus_name=com.example.FooBar
279 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
281 sion:
282 \--tcti:bus_type=session
284 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 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 • 0 - Success.
300 • 1 - General non-specific error.
302 • 2 - Options handling error.
304 • 3 - Authentication error.
306 • 4 - TCTI related error.
308 • 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)
316tpm2-tools tpm2_clearcontrol(1)