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

NAME

6       tpm2_clearcontrol(1) - Set/ Clear TPMA_PERMANENT.disableClear attribute
7       to effectively block/ unblock lockout authorization handle for  issuing
8       TPM clear.
9

SYNOPSIS

11       tpm2_clearcontrol [OPTIONS] [ARGUMENT]
12

DESCRIPTION

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

OPTIONS

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
44ARGUMENT ** Specify an integer 0|1 or string c|s to clear or set  the
45         disableClear attribute.
46
47   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

247       This collection of options are used to configure the various known TCTI
248       modules available:
249
250device: 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
256mssim:  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
263abrmd: 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

EXAMPLES

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

Returns

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

BUGS

312       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
313

HELP

315       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
316
317
318
319tpm2-tools                                                tpm2_clearcontrol(1)
Impressum