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

NAME

6       tpm2_clockrateadjust(1) - Sets the clock rate period on the TPM.
7

SYNOPSIS

9       tpm2_clockrateadjust [OPTIONS] ADJUSTER
10

DESCRIPTION

12       tpm2_clockrateadjust(1)  - Adjusts the rate at which clock and time are
13       updated on the TPM so one can better match real time.   With  no  argu‐
14       ment,  the  command is invoked but the clock rate is not altered.  With
15       an argument, the tool will adjust the clock and time period.  The  com‐
16       mand  can  either  increase or decrease the clock period via 3 distinct
17       granularities: course, medium and fine.  To specify this, the  argument
18       can be a string of 1 to 3 characters of all 's' or 'f'.
19
20   Valid Adjuster Arguments
21       · s - slows down the clock period one fine increment.
22
23       · ss - slows down the clock period one medium increment.
24
25       · sss - slows down the clock period one course increment.
26
27       · f - speeds up the clock period one fine increment.
28
29       · ff - speeds up the clock period one medium increment.
30
31       · fff - speeds up the clock period one course increment.
32

OPTIONS

34       · -c, --hierarchy=OBJECT:
35
36         The  hierarchy  to  use  for authorization, either platform or owner.
37         Defaults to the owner hierarchy if not specified.
38
39       · -p, --auth=AUTH:
40
41         Specifies the authorization value for the hierarchy specified by  op‐
42         tion -c.
43
44       · --cphash=FILE
45
46         File path to record the hash of the command parameters.  This is com‐
47         monly termed as cpHash.  NOTE: When this option is selected, The tool
48         will not actually execute the command, it simply returns a cpHash.
49
50   References

Context Object Format

52       The  type  of a context object, whether it is a handle or file name, is
53       determined according to the following logic in-order:
54
55       · If the argument is a file path, then the file is loaded as a restored
56         TPM transient object.
57
58       · If the argument is a prefix match on one of:
59
60         · owner: the owner hierarchy
61
62         · platform: the platform hierarchy
63
64         · endorsement: the endorsement hierarchy
65
66         · lockout: the lockout control persistent object
67
68       · If  the  argument argument can be loaded as a number it will be treat
69         as a handle, e.g.  0x81010013 and used directly.OBJECT.
70

Authorization Formatting

72       Authorization for use of an object in TPM2.0 can come  in  3  different
73       forms: 1.  Password 2.  HMAC 3.  Sessions
74
75       NOTE:  "Authorizations  default  to  the EMPTY PASSWORD when not speci‐
76       fied".
77
78   Passwords
79       Passwords are interpreted in the following  forms  below  using  prefix
80       identifiers.
81
82       Note:  By  default  passwords are assumed to be in the string form when
83       they do not have a prefix.
84
85   String
86       A string password, specified by prefix  "str:"  or  it's  absence  (raw
87       string without prefix) is not interpreted, and is directly used for au‐
88       thorization.
89
90   Examples
91              foobar
92              str:foobar
93
94   Hex-string
95       A hex-string password, specified by prefix "hex:" is converted  from  a
96       hexidecimal  form  into a byte array form, thus allowing passwords with
97       non-printable and/or terminal un-friendly characters.
98
99   Example
100              hex:0x1122334455667788
101
102   File
103       A file based password, specified be prefix "file:" should be  the  path
104       of  a  file  containing the password to be read by the tool or a "-" to
105       use stdin.  Storing passwords in files  prevents  information  leakage,
106       passwords passed as options can be read from the process list or common
107       shell history features.
108
109   Examples
110              # to use stdin and be prompted
111              file:-
112
113              # to use a file from a path
114              file:path/to/password/file
115
116              # to echo a password via stdin:
117              echo foobar | tpm2_tool -p file:-
118
119              # to use a bash here-string via stdin:
120
121              tpm2_tool -p file:- <<< foobar
122
123   Sessions
124       When using a policy session to authorize the use of an  object,  prefix
125       the  option argument with the session keyword.  Then indicate a path to
126       a session file that was created with tpm2_startauthsession(1).  Option‐
127       ally, if the session requires an auth value to be sent with the session
128       handle (eg policy password), then append a + and a string as  described
129       in the Passwords section.
130
131   Examples
132       To use a session context file called session.ctx.
133
134              session:session.ctx
135
136       To use a session context file called session.ctx AND send the authvalue
137       mypassword.
138
139              session:session.ctx+mypassword
140
141       To use a session context file called session.ctx AND send the HEX auth‐
142       value 0x11223344.
143
144              session:session.ctx+hex:11223344
145
146   PCR Authorizations
147       You  can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
148       language.      The     PCR     minilanguage     is     as      follows:
149       <pcr-spec>=<raw-pcr-file>
150
151       The PCR spec is documented in in the section "PCR bank specifiers".
152
153       The  raw-pcr-file  is an optional the output of the raw PCR contents as
154       returned by tpm2_pcrread(1).
155
156       PCR bank specifiers (common/pcr.md)
157
158   Examples
159       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
160       er of:
161
162              pcr:sha256:0,1,2,3
163
164       specifying AUTH.
165

COMMON OPTIONS

167       This  collection of options are common to many programs and provide in‐
168       formation that many users may expect.
169
170       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
171         attempts  to  invoke  the  manpager for the tool, however, on failure
172         will output a short tool summary.  This is the same behavior  if  the
173         "man"  option argument is specified, however if explicit "man" is re‐
174         quested, the tool will provide errors from man  on  stderr.   If  the
175         "no-man"  option  if  specified, or the manpager fails, the short op‐
176         tions will be output to stdout.
177
178         To successfully use the manpages feature requires the manpages to  be
179         installed or on MANPATH, See man(1) for more details.
180
181       · -v,  --version:  Display version information for this tool, supported
182         tctis and exit.
183
184       · -V, --verbose: Increase the information that the tool prints  to  the
185         console  during  its  execution.  When using this option the file and
186         line number are printed.
187
188       · -Q, --quiet: Silence normal tool output to stdout.
189
190       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
191         if  an  errata fixup needs to be applied to commands sent to the TPM.
192         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
193         formation many users may expect.
194

TCTI Configuration

196       The  TCTI  or  "Transmission  Interface" is the communication mechanism
197       with the TPM.  TCTIs can be changed for communication with TPMs  across
198       different mediums.
199
200       To control the TCTI, the tools respect:
201
202       1. The command line option -T or --tcti
203
204       2. The environment variable: TPM2TOOLS_TCTI.
205
206       Note:  The  command  line option always overrides the environment vari‐
207       able.
208
209       The current known TCTIs are:
210
211       · tabrmd     -     The     resource     manager,     called      tabrmd
212         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
213         abrmd as a tcti name are synonymous.
214
215       · mssim - Typically used for communicating to the TPM software  simula‐
216         tor.
217
218       · device - Used when talking directly to a TPM device file.
219
220       · none  - Do not initalize a connection with the TPM.  Some tools allow
221         for off-tpm options and thus support not using a TCTI.  Tools that do
222         not  support  it  will error when attempted to be used without a TCTI
223         connection.  Does not support ANY options and MUST  BE  presented  as
224         the exact text of "none".
225
226       The  arguments  to  either  the  command line option or the environment
227       variable are in the form:
228
229       <tcti-name>:<tcti-option-config>
230
231       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
232       tion-config> results in the default being used for that portion respec‐
233       tively.
234
235   TCTI Defaults
236       When a TCTI is not specified, the default TCTI is  searched  for  using
237       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
238       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
239       what TCTI will be chosen as the default by using the -v option to print
240       the version information.  The "default-tcti" key-value pair will  indi‐
241       cate which of the aforementioned TCTIs is the default.
242
243   Custom TCTIs
244       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
245       tools internally use dlopen(3), and the raw tcti-name value is used for
246       the lookup.  Thus, this could be a path to the shared library, or a li‐
247       brary name as understood by dlopen(3) semantics.
248

TCTI OPTIONS

250       This collection of options are used to configure the various known TCTI
251       modules available:
252
253       · device: For the device TCTI, the TPM character device file for use by
254         the device TCTI can be specified.  The default is /dev/tpm0.
255
256         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
257         vice:/dev/tpm0"
258
259       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
260         number used by the simulator  can  be  specified.   The  default  are
261         127.0.0.1 and 2321.
262
263         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
264         TI="mssim:host=localhost,port=2321"
265
266       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
267         ries  of  simple  key value pairs separated by a ',' character.  Each
268         key and value string are separated by a '=' character.
269
270         · TCTI abrmd supports two keys:
271
272           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
273              string).
274
275           2. 'bus_type' : The type of the dbus instance (a string) limited to
276              'session' and 'system'.
277
278         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
279         ample.FooBar:
280
281         \--tcti=tabrmd:bus_name=com.example.FooBar
282
283         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
284         sion:
285
286         \--tcti:bus_type=session
287
288         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
289         ules.
290

EXAMPLES

292   Set the clock
293       Slow the clock one medium increment using the owner password.
294
295              tpm2_clockrateadjust -p ownerpw ss
296
297       Speed up the clock one course increment using the platform password.
298
299              tpm2_clockrateadjust -c p -p platformpw fff
300

Returns

302       Tools can return any of the following codes:
303
304       · 0 - Success.
305
306       · 1 - General non-specific error.
307
308       · 2 - Options handling error.
309
310       · 3 - Authentication error.
311
312       · 4 - TCTI related error.
313
314       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
315

BUGS

317       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
318

HELP

320       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
321
322
323
324tpm2-tools                                             tpm2_clockrateadjust(1)
Impressum