1tpm2_startauthsession(1) General Commands Manual tpm2_startauthsession(1)
2
6 tpm2_startauthsession(1) - Start a session with the TPM.
7
9 tpm2_startauthsession [OPTIONS]
10
12 tpm2_startauthsession(1) - Starts a session with the TPM. The default
13 is to start a trial session unless the -a option is specified. Saves
14 the policy session data to a file. This file can then be used in sub‐
15 sequent tools that can use a policy file for authorization or policy
16 events.
17 This will not work with resource managers (RMs) outside of tpm2-abrmd
19 (https://github.com/tpm2-software/tpm2-abrmd), as most RMs will flush
20 session handles when a client disconnects from the IPC channel. Howev‐
21 er, when using a RM without the session gapping feature, one can use
22 the command TCTI to keep the connection open.
23 The first step is to create a socket listener that uses tpm2_send:
25 mknod "$HOME/backpipe" p
27 while [ 1 ]; do tpm2_send 0<"$HOME/backpipe" | nc -lU "$HOME/sock" 1>"$HOME/backpipe"; done;
28 The next step is to use the command TCTI and netcat (nc) to send data
30 to the socket.
31 tpm2_startauthsession --tcti="cmd:nc -q 0 -U $HOME/sock" <options>
33 When finishing ensure to kill the listener. For commands executed with
35 the command tcti against the listener, one will need to manage tran‐
36 sient handles. The simplest way is to add a flush after each command:
37 tpm2_flushcontext --tcti="cmd:nc -q 0 -U $HOME/sock" -t
38 Note: This example uses UNIX sockets, since the socket is controlled
40 with Linux access controls. Using a port is not recommended as it’s
41 either open to any user on the system (localhost) or bound to a network
42 card and exposed to the network.
43 This will work with direct TPM access, but note that internally this
45 calls a ContextSave and a ContextLoad on the session handle, thus the
46 session cannot be saved/loaded again.
47
49 • --policy-session:
50 Start a policy session of type TPM_SE_POLICY. Default without this
52 option is TPM_SE_TRIAL.
53 NOTE: A trial session is used when building a policy and a policy
55 session is used when authenticating with a policy.
56 • --audit-session:
58 Start an HMAC session to be used as an audit session. Default with‐
60 out this option is TPM2_SE_TRIAL.
61 • --hmac-session:
63 Start an HMAC session of type TPM_SE_HMAC. Default without this op‐
65 tion is TPM2_SE_TRIAL.
66 • -g, --hash-algorithm=ALGORITHM:
68 The hash algorithm used in computation of the policy digest.
70 • -G, --key-algorithm=ALGORITHM:
72 The symmetric algorithm used in parameter encryption/decryption.
74 • -c, --key-context=OBJECT:
76 Set the tpmkey and bind objects to be the same. Session parameter
78 encryption is turned on. Session parameter decryption is turned on.
79 Parameter encryption/decryption symmetric-key set to AES-CFB.
80 • -S, --session=FILE:
82 The name of the policy session file, required.
84 • --bind-context=FILE:
86 Set the bind object. Session parameter encryption is off. Use
88 tpm2_sessionconfig to turn on. Session parameter decryption is off.
89 Use tpm2_sessionconfig to turn on. Parameter encryption/decryption
90 symmetric-key set to AES-CFB.
91 • --bind-auth=AUTH:
93 Set the authorization value for the bind object.
95 • --tpmkey-context=FILE:
97 Set the tpmkey object. Session parameter encryption is off. Use
99 tpm2_sessionconfig to turn on. Session parameter decryption is off.
100 Use tpm2_sessionconfig to turn on. Parameter encryption/decryption
101 symmetric-key set to AES-CFB.
102 • -n, --name=FILE
104 A name file as output from a tool like tpm2_readpublic(1) -n option.
106 The name file can be used to verify a persistent handle input for the
107 --tpmkey-context, -c, and --key-context options. Verification that
108 the object referenced by a peristent handle, e.g 0x81000000, is the
109 key expected prevents attackers from performing a man-in-the-middle
110 attack on session traffic.
111 References
114 The type of a context object, whether it is a handle or file name, is
115 determined according to the following logic in-order:
116 • If the argument is a file path, then the file is loaded as a restored
118 TPM transient object.
119 • If the argument is a prefix match on one of:
121 • owner: the owner hierarchy
123 • platform: the platform hierarchy
125 • endorsement: the endorsement hierarchy
127 • lockout: the lockout control persistent object
129 • If the argument argument can be loaded as a number it will be treat
131 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
132
134 Authorization for use of an object in TPM2.0 can come in 3 different
135 forms: 1. Password 2. HMAC 3. Sessions
136 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
138 fied”.
139 Passwords
141 Passwords are interpreted in the following forms below using prefix
142 identifiers.
143 Note: By default passwords are assumed to be in the string form when
145 they do not have a prefix.
146 String
148 A string password, specified by prefix “str:” or it’s absence (raw
149 string without prefix) is not interpreted, and is directly used for au‐
150 thorization.
151 Examples
153 foobar
154 str:foobar
155 Hex-string
157 A hex-string password, specified by prefix “hex:” is converted from a
158 hexidecimal form into a byte array form, thus allowing passwords with
159 non-printable and/or terminal un-friendly characters.
160 Example
162 hex:1122334455667788
163 File
165 A file based password, specified be prefix “file:” should be the path
166 of a file containing the password to be read by the tool or a “-” to
167 use stdin. Storing passwords in files prevents information leakage,
168 passwords passed as options can be read from the process list or common
169 shell history features.
170 Examples
172 # to use stdin and be prompted
173 file:-
174 # to use a file from a path
176 file:path/to/password/file
177 # to echo a password via stdin:
179 echo foobar | tpm2_tool -p file:-
180 # to use a bash here-string via stdin:
182 tpm2_tool -p file:- <<< foobar
184 Sessions
186 When using a policy session to authorize the use of an object, prefix
187 the option argument with the session keyword. Then indicate a path to
188 a session file that was created with tpm2_startauthsession(1). Option‐
189 ally, if the session requires an auth value to be sent with the session
190 handle (eg policy password), then append a + and a string as described
191 in the Passwords section.
192 Examples
194 To use a session context file called session.ctx.
195 session:session.ctx
197 To use a session context file called session.ctx AND send the authvalue
199 mypassword.
200 session:session.ctx+mypassword
202 To use a session context file called session.ctx AND send the HEX auth‐
204 value 0x11223344.
205 session:session.ctx+hex:11223344
207 PCR Authorizations
209 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
210 language. The PCR minilanguage is as follows:
211 <pcr-spec>=<raw-pcr-file>
212 The PCR spec is documented in in the section “PCR bank specifiers”.
214 The raw-pcr-file is an optional argument that contains the output of
216 the raw PCR contents as returned by tpm2_pcrread(1).
217 PCR bank specifiers (pcr.md)
219 Examples
221 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
222 er of:
223 pcr:sha256:0,1,2,3
225 specifying AUTH.
227
229 This collection of options are common to many programs and provide in‐
230 formation that many users may expect.
231 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
233 attempts to invoke the manpager for the tool, however, on failure
234 will output a short tool summary. This is the same behavior if the
235 “man” option argument is specified, however if explicit “man” is re‐
236 quested, the tool will provide errors from man on stderr. If the
237 “no-man” option if specified, or the manpager fails, the short op‐
238 tions will be output to stdout.
239 To successfully use the manpages feature requires the manpages to be
241 installed or on MANPATH, See man(1) for more details.
242 • -v, --version: Display version information for this tool, supported
244 tctis and exit.
245 • -V, --verbose: Increase the information that the tool prints to the
247 console during its execution. When using this option the file and
248 line number are printed.
249 • -Q, --quiet: Silence normal tool output to stdout.
251 • -Z, --enable-errata: Enable the application of errata fixups. Useful
253 if an errata fixup needs to be applied to commands sent to the TPM.
254 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
255 formation many users may expect.
256
258 The TCTI or “Transmission Interface” is the communication mechanism
259 with the TPM. TCTIs can be changed for communication with TPMs across
260 different mediums.
261 To control the TCTI, the tools respect:
263 1. The command line option -T or --tcti
265 2. The environment variable: TPM2TOOLS_TCTI.
267 Note: The command line option always overrides the environment vari‐
269 able.
270 The current known TCTIs are:
272 • tabrmd - The resource manager, called tabrmd
274 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
275 abrmd as a tcti name are synonymous.
276 • mssim - Typically used for communicating to the TPM software simula‐
278 tor.
279 • device - Used when talking directly to a TPM device file.
281 • none - Do not initalize a connection with the TPM. Some tools allow
283 for off-tpm options and thus support not using a TCTI. Tools that do
284 not support it will error when attempted to be used without a TCTI
285 connection. Does not support ANY options and MUST BE presented as
286 the exact text of “none”.
287 The arguments to either the command line option or the environment
289 variable are in the form:
290 <tcti-name>:<tcti-option-config>
292 Specifying an empty string for either the <tcti-name> or <tcti-op‐
294 tion-config> results in the default being used for that portion respec‐
295 tively.
296 TCTI Defaults
298 When a TCTI is not specified, the default TCTI is searched for using
299 dlopen(3) semantics. The tools will search for tabrmd, device and
300 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
301 what TCTI will be chosen as the default by using the -v option to print
302 the version information. The “default-tcti” key-value pair will indi‐
303 cate which of the aforementioned TCTIs is the default.
304 Custom TCTIs
306 Any TCTI that implements the dynamic TCTI interface can be loaded. The
307 tools internally use dlopen(3), and the raw tcti-name value is used for
308 the lookup. Thus, this could be a path to the shared library, or a li‐
309 brary name as understood by dlopen(3) semantics.
310
312 This collection of options are used to configure the various known TCTI
313 modules available:
314 • device: For the device TCTI, the TPM character device file for use by
316 the device TCTI can be specified. The default is /dev/tpm0.
317 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
319 vice:/dev/tpm0”
320 • mssim: For the mssim TCTI, the domain name or IP address and port
322 number used by the simulator can be specified. The default are
323 127.0.0.1 and 2321.
324 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
326 TI=“mssim:host=localhost,port=2321”
327 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
329 ries of simple key value pairs separated by a `,' character. Each
330 key and value string are separated by a `=' character.
331 • TCTI abrmd supports two keys:
333 1. `bus_name' : The name of the tabrmd service on the bus (a
335 string).
336 2. `bus_type' : The type of the dbus instance (a string) limited to
338 `session' and `system'.
339 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
341 ample.FooBar:
342 \--tcti=tabrmd:bus_name=com.example.FooBar
344 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
346 sion:
347 \--tcti:bus_type=session
349 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
351 ules. # EXAMPLES
352 Start a trial session and save the session data to a file
354 tpm2_startauthsession -S mysession.ctx
355 Start a policy session and save the session data to a file
357 tpm2_startauthsession --policy-session -S mysession.ctx
358 Start an encrypted and bound policy session and save the session data to a
360 file
361 tpm2_createprimary -c primary.ctx
362 tpm2_startauthsession --policy-session -c primary.ctx -S mysession.ctx
363
365 Tools can return any of the following codes:
366 • 0 - Success.
368 • 1 - General non-specific error.
370 • 2 - Options handling error.
372 • 3 - Authentication error.
374 • 4 - TCTI related error.
376 • 5 - Non supported scheme. Applicable to tpm2_testparams.
378
380 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
381
383 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
384 fo/tpm2)
385tpm2-tools tpm2_startauthsession(1)