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

NAME

6       tpm2_dictionarylockout(1)  -  Setup  or clear dictionary-attack-lockout
7       parameters.
8

SYNOPSIS

10       tpm2_dictionarylockout [OPTIONS]
11

DESCRIPTION

13       tpm2_dictionarylockout(1) - Setup dictionary-attack-lockout  parameters
14       or clear dictionary-attack-lockout state.
15

OPTIONS

17-s, --setup-parameters:
18
19         Specifies  the tool should operate to setup dictionary-attack-lockout
20         parameters.
21
22-c, --clear-lockout:
23
24         Specifies the tool should operate to clear  dictionary-attack-lockout
25         state.
26
27-l, --lockout-recovery-time=NATURAL_NUMBER:
28
29         Specifies  the wait time in seconds before another TPM_RH_LOCKOUT au‐
30         thentication attempt can be made after a failed authentication.
31
32-t, --recovery-time=NATURAL_NUMBER:
33
34         Specifies the wait time in seconds before another DA-protected-object
35         authentication  attempt  can be made after max-tries number of failed
36         authentications.
37
38-n, --max-tries=NATURAL_NUMBER:
39
40         Specifies the maximum number of allowed  authentication  attempts  on
41         DA-protected-object; after which DA is activated.
42
43-p, --auth=AUTH:
44
45         The authorization value for the lockout handle.
46
47--cphash=FILE
48
49         File path to record the hash of the command parameters.  This is com‐
50         monly termed as cpHash.  NOTE: When this option is selected, The tool
51         will not actually execute the command, it simply returns a cpHash.
52
53   References

Authorization Formatting

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

COMMON OPTIONS

150       This collection of options are common to many programs and provide  in‐
151       formation that many users may expect.
152
153-h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
154         attempts to invoke the manpager for the  tool,  however,  on  failure
155         will  output  a short tool summary.  This is the same behavior if the
156         “man” option argument is specified, however if explicit “man” is  re‐
157         quested,  the  tool  will  provide errors from man on stderr.  If the
158         “no-man” option if specified, or the manpager fails,  the  short  op‐
159         tions will be output to stdout.
160
161         To  successfully use the manpages feature requires the manpages to be
162         installed or on MANPATH, See man(1) for more details.
163
164-v, --version: Display version information for this  tool,  supported
165         tctis and exit.
166
167-V,  --verbose:  Increase the information that the tool prints to the
168         console during its execution.  When using this option  the  file  and
169         line number are printed.
170
171-Q, --quiet: Silence normal tool output to stdout.
172
173-Z, --enable-errata: Enable the application of errata fixups.  Useful
174         if an errata fixup needs to be applied to commands sent to  the  TPM.
175         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
176         formation many users may expect.
177

TCTI Configuration

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

TCTI OPTIONS

233       This collection of options are used to configure the various known TCTI
234       modules available:
235
236device: For the device TCTI, the TPM character device file for use by
237         the device TCTI can be specified.  The default is /dev/tpm0.
238
239         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
240         vice:/dev/tpm0”
241
242mssim: For the mssim TCTI, the domain name or  IP  address  and  port
243         number  used  by  the  simulator  can  be specified.  The default are
244         127.0.0.1 and 2321.
245
246         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
247         TI=“mssim:host=localhost,port=2321”
248
249abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
250         ries of simple key value pairs separated by a  `,'  character.   Each
251         key and value string are separated by a `=' character.
252
253         • TCTI abrmd supports two keys:
254
255           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
256              string).
257
258           2. `bus_type' : The type of the dbus instance (a string) limited to
259              `session' and `system'.
260
261         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
262         ample.FooBar:
263
264                \--tcti=tabrmd:bus_name=com.example.FooBar
265
266         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
267         sion:
268
269                \--tcti:bus_type=session
270
271         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
272         ules.
273

EXAMPLES

275              tpm2_dictionarylockout -c -p passwd
276
277              tpm2_dictionarylockout -s -n 5 -t 6 -l 7 -p passwd
278

Returns

280       Tools can return any of the following codes:
281
282       • 0 - Success.
283
284       • 1 - General non-specific error.
285
286       • 2 - Options handling error.
287
288       • 3 - Authentication error.
289
290       • 4 - TCTI related error.
291
292       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
293

BUGS

295       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
296

HELP

298       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
299
300
301
302tpm2-tools                                           tpm2_dictionarylockout(1)
Impressum