1tpm2_dictionarylockout(1) General Commands Manual tpm2_dictionarylockout(1)
2
6 tpm2_dictionarylockout(1) - Setup or clear dictionary-attack-lockout
7 parameters.
8
10 tpm2_dictionarylockout [OPTIONS]
11
13 tpm2_dictionarylockout(1) - Setup dictionary-attack-lockout parameters
14 or clear dictionary-attack-lockout state.
15
17 · -s, --setup-parameters:
18 Specifies the tool should operate to setup dictionary-attack-lockout
20 parameters.
21 · -c, --clear-lockout:
23 Specifies the tool should operate to clear dictionary-attack-lockout
25 state.
26 · -l, --lockout-recovery-time=NATURAL_NUMBER:
28 Specifies the wait time in seconds before another TPM_RH_LOCKOUT au‐
30 thentication attempt can be made after a failed authentication.
31 · -t, --recovery-time=NATURAL_NUMBER:
33 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 · -n, --max-tries=NATURAL_NUMBER:
39 Specifies the maximum number of allowed authentication attempts on
41 DA-protected-object; after which DA is activated.
42 · -p, --auth=AUTH:
44 The authorization value for the lockout handle.
46 References
49 Authorization for use of an object in TPM2.0 can come in 3 different
50 forms: 1. Password 2. HMAC 3. Sessions
51 NOTE: "Authorizations default to the EMPTY PASSWORD when not speci‐
53 fied".
54 Passwords
56 Passwords are interpreted in the following forms below using prefix
57 identifiers.
58 Note: By default passwords are assumed to be in the string form when
60 they do not have a prefix.
61 String
63 A string password, specified by prefix "str:" or it's absence (raw
64 string without prefix) is not interpreted, and is directly used for au‐
65 thorization.
66 Examples
68 foobar
69 str:foobar
70 Hex-string
72 A hex-string password, specified by prefix "hex:" is converted from a
73 hexidecimal form into a byte array form, thus allowing passwords with
74 non-printable and/or terminal un-friendly characters.
75 Example
77 hex:0x1122334455667788
78 File
80 A file based password, specified be prefix "file:" should be the path
81 of a file containing the password to be read by the tool or a "-" to
82 use stdin. Storing passwords in files prevents information leakage,
83 passwords passed as options can be read from the process list or common
84 shell history features.
85 Examples
87 # to use stdin and be prompted
88 file:-
89 # to use a file from a path
91 file:path/to/password/file
92 # to echo a password via stdin:
94 echo foobar | tpm2_tool -p file:-
95 # to use a bash here-string via stdin:
97 tpm2_tool -p file:- <<< foobar
99 Sessions
101 When using a policy session to authorize the use of an object, prefix
102 the option argument with the session keyword. Then indicate a path to
103 a session file that was created with tpm2_startauthsession(1). Option‐
104 ally, if the session requires an auth value to be sent with the session
105 handle (eg policy password), then append a + and a string as described
106 in the Passwords section.
107 Examples
109 To use a session context file called session.ctx.
110 session:session.ctx
112 To use a session context file called session.ctx AND send the authvalue
114 mypassword.
115 session:session.ctx+mypassword
117 To use a session context file called session.ctx AND send the HEX auth‐
119 value 0x11223344.
120 session:session.ctx+hex:11223344
122 PCR Authorizations
124 You can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
125 language. The PCR minilanguage is as follows:
126 <pcr-spec>=<raw-pcr-file>
127 The PCR spec is documented in in the section "PCR bank specifiers".
129 The raw-pcr-file is an optional the output of the raw PCR contents as
131 returned by tpm2_pcrread(1).
132 PCR bank specifiers (common/pcr.md)
134 Examples
136 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
137 er of:
138 pcr:sha256:0,1,2,3
140 specifying AUTH.
142
144 This collection of options are common to many programs and provide in‐
145 formation that many users may expect.
146 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
148 attempts to invoke the manpager for the tool, however, on failure
149 will output a short tool summary. This is the same behavior if the
150 "man" option argument is specified, however if explicit "man" is re‐
151 quested, the tool will provide errors from man on stderr. If the
152 "no-man" option if specified, or the manpager fails, the short op‐
153 tions will be output to stdout.
154 To successfully use the manpages feature requires the manpages to be
156 installed or on MANPATH, See man(1) for more details.
157 · -v, --version: Display version information for this tool, supported
159 tctis and exit.
160 · -V, --verbose: Increase the information that the tool prints to the
162 console during its execution. When using this option the file and
163 line number are printed.
164 · -Q, --quiet: Silence normal tool output to stdout.
166 · -Z, --enable-errata: Enable the application of errata fixups. Useful
168 if an errata fixup needs to be applied to commands sent to the TPM.
169 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
170 formation many users may expect.
171
173 The TCTI or "Transmission Interface" is the communication mechanism
174 with the TPM. TCTIs can be changed for communication with TPMs across
175 different mediums.
176 To control the TCTI, the tools respect:
178 1. The command line option -T or --tcti
180 2. The environment variable: TPM2TOOLS_TCTI.
182 Note: The command line option always overrides the environment vari‐
184 able.
185 The current known TCTIs are:
187 · tabrmd - The resource manager, called tabrmd
189 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
190 abrmd as a tcti name are synonymous.
191 · mssim - Typically used for communicating to the TPM software simula‐
193 tor.
194 · device - Used when talking directly to a TPM device file.
196 · none - Do not initalize a connection with the TPM. Some tools allow
198 for off-tpm options and thus support not using a TCTI. Tools that do
199 not support it will error when attempted to be used without a TCTI
200 connection. Does not support ANY options and MUST BE presented as
201 the exact text of "none".
202 The arguments to either the command line option or the environment
204 variable are in the form:
205 <tcti-name>:<tcti-option-config>
207 Specifying an empty string for either the <tcti-name> or <tcti-op‐
209 tion-config> results in the default being used for that portion respec‐
210 tively.
211 TCTI Defaults
213 When a TCTI is not specified, the default TCTI is searched for using
214 dlopen(3) semantics. The tools will search for tabrmd, device and
215 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
216 what TCTI will be chosen as the default by using the -v option to print
217 the version information. The "default-tcti" key-value pair will indi‐
218 cate which of the aforementioned TCTIs is the default.
219 Custom TCTIs
221 Any TCTI that implements the dynamic TCTI interface can be loaded. The
222 tools internally use dlopen(3), and the raw tcti-name value is used for
223 the lookup. Thus, this could be a path to the shared library, or a li‐
224 brary name as understood by dlopen(3) semantics.
225
227 This collection of options are used to configure the various known TCTI
228 modules available:
229 · device: For the device TCTI, the TPM character device file for use by
231 the device TCTI can be specified. The default is /dev/tpm0.
232 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
234 vice:/dev/tpm0"
235 · mssim: For the mssim TCTI, the domain name or IP address and port
237 number used by the simulator can be specified. The default are
238 127.0.0.1 and 2321.
239 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
241 TI="mssim:host=localhost,port=2321"
242 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
244 ries of simple key value pairs separated by a ',' character. Each
245 key and value string are separated by a '=' character.
246 · TCTI abrmd supports two keys:
248 1. 'bus_name' : The name of the tabrmd service on the bus (a
250 string).
251 2. 'bus_type' : The type of the dbus instance (a string) limited to
253 'session' and 'system'.
254 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
256 ample.FooBar:
257 \--tcti=tabrmd:bus_name=com.example.FooBar
259 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
261 sion:
262 \--tcti:bus_type=session
264 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
266 ules.
267
269 tpm2_dictionarylockout -c -p passwd
270 tpm2_dictionarylockout -s -n 5 -t 6 -l 7 -p passwd
272
274 Tools can return any of the following codes:
275 · 0 - Success.
277 · 1 - General non-specific error.
279 · 2 - Options handling error.
281 · 3 - Authentication error.
283 · 4 - TCTI related error.
285 · 5 - Non supported scheme. Applicable to tpm2_testparams.
287
289 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
290
292 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
293tpm2-tools tpm2_dictionarylockout(1)