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://%20github.com/tpm2-software/tpm2-abrmd), as most RMs will
20 flush session handles when a client disconnects from the IPC channel.
21 However, when using a RM without the session gapping feature, one can
22 use 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 • -c, --key-context=OBJECT:
72 Set the tpmkey and bind objects to be the same. Session parameter
74 encryption is turned on. Session parameter decryption is turned on.
75 Parameter encryption/decryption symmetric-key set to AES-CFB.
76 • -S, --session=FILE:
78 The name of the policy session file, required.
80 • --bind-context=FILE:
82 Set the bind object. Session parameter encryption is off. Use
84 tpm2_sessionconfig to turn on. Session parameter decryption is off.
85 Use tpm2_sessionconfig to turn on. Parameter encryption/decryption
86 symmetric-key set to AES-CFB.
87 • --bind-auth=AUTH:
89 Set the authorization value for the bind object.
91 • --tpmkey-context=FILE:
93 Set the tpmkey object. Session parameter encryption is off. Use
95 tpm2_sessionconfig to turn on. Session parameter decryption is off.
96 Use tpm2_sessionconfig to turn on. Parameter encryption/decryption
97 symmetric-key set to AES-CFB.
98 References
101 The type of a context object, whether it is a handle or file name, is
102 determined according to the following logic in-order:
103 • If the argument is a file path, then the file is loaded as a restored
105 TPM transient object.
106 • If the argument is a prefix match on one of:
108 • owner: the owner hierarchy
110 • platform: the platform hierarchy
112 • endorsement: the endorsement hierarchy
114 • lockout: the lockout control persistent object
116 • If the argument argument can be loaded as a number it will be treat
118 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
119
121 Authorization for use of an object in TPM2.0 can come in 3 different
122 forms: 1. Password 2. HMAC 3. Sessions
123 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
125 fied”.
126 Passwords
128 Passwords are interpreted in the following forms below using prefix
129 identifiers.
130 Note: By default passwords are assumed to be in the string form when
132 they do not have a prefix.
133 String
135 A string password, specified by prefix “str:” or it’s absence (raw
136 string without prefix) is not interpreted, and is directly used for au‐
137 thorization.
138 Examples
140 foobar
141 str:foobar
142 Hex-string
144 A hex-string password, specified by prefix “hex:” is converted from a
145 hexidecimal form into a byte array form, thus allowing passwords with
146 non-printable and/or terminal un-friendly characters.
147 Example
149 hex:0x1122334455667788
150 File
152 A file based password, specified be prefix “file:” should be the path
153 of a file containing the password to be read by the tool or a “-” to
154 use stdin. Storing passwords in files prevents information leakage,
155 passwords passed as options can be read from the process list or common
156 shell history features.
157 Examples
159 # to use stdin and be prompted
160 file:-
161 # to use a file from a path
163 file:path/to/password/file
164 # to echo a password via stdin:
166 echo foobar | tpm2_tool -p file:-
167 # to use a bash here-string via stdin:
169 tpm2_tool -p file:- <<< foobar
171 Sessions
173 When using a policy session to authorize the use of an object, prefix
174 the option argument with the session keyword. Then indicate a path to
175 a session file that was created with tpm2_startauthsession(1). Option‐
176 ally, if the session requires an auth value to be sent with the session
177 handle (eg policy password), then append a + and a string as described
178 in the Passwords section.
179 Examples
181 To use a session context file called session.ctx.
182 session:session.ctx
184 To use a session context file called session.ctx AND send the authvalue
186 mypassword.
187 session:session.ctx+mypassword
189 To use a session context file called session.ctx AND send the HEX auth‐
191 value 0x11223344.
192 session:session.ctx+hex:11223344
194 PCR Authorizations
196 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
197 language. The PCR minilanguage is as follows:
198 <pcr-spec>=<raw-pcr-file>
199 The PCR spec is documented in in the section “PCR bank specifiers”.
201 The raw-pcr-file is an optional argument that contains the output of
203 the raw PCR contents as returned by tpm2_pcrread(1).
204 PCR bank specifiers (pcr.md)
206 Examples
208 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
209 er of:
210 pcr:sha256:0,1,2,3
212 specifying AUTH.
214
216 This collection of options are common to many programs and provide in‐
217 formation that many users may expect.
218 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
220 attempts to invoke the manpager for the tool, however, on failure
221 will output a short tool summary. This is the same behavior if the
222 “man” option argument is specified, however if explicit “man” is re‐
223 quested, the tool will provide errors from man on stderr. If the
224 “no-man” option if specified, or the manpager fails, the short op‐
225 tions will be output to stdout.
226 To successfully use the manpages feature requires the manpages to be
228 installed or on MANPATH, See man(1) for more details.
229 • -v, --version: Display version information for this tool, supported
231 tctis and exit.
232 • -V, --verbose: Increase the information that the tool prints to the
234 console during its execution. When using this option the file and
235 line number are printed.
236 • -Q, --quiet: Silence normal tool output to stdout.
238 • -Z, --enable-errata: Enable the application of errata fixups. Useful
240 if an errata fixup needs to be applied to commands sent to the TPM.
241 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
242 formation many users may expect.
243
245 The TCTI or “Transmission Interface” is the communication mechanism
246 with the TPM. TCTIs can be changed for communication with TPMs across
247 different mediums.
248 To control the TCTI, the tools respect:
250 1. The command line option -T or --tcti
252 2. The environment variable: TPM2TOOLS_TCTI.
254 Note: The command line option always overrides the environment vari‐
256 able.
257 The current known TCTIs are:
259 • tabrmd - The resource manager, called tabrmd
261 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
262 abrmd as a tcti name are synonymous.
263 • mssim - Typically used for communicating to the TPM software simula‐
265 tor.
266 • device - Used when talking directly to a TPM device file.
268 • none - Do not initalize a connection with the TPM. Some tools allow
270 for off-tpm options and thus support not using a TCTI. Tools that do
271 not support it will error when attempted to be used without a TCTI
272 connection. Does not support ANY options and MUST BE presented as
273 the exact text of “none”.
274 The arguments to either the command line option or the environment
276 variable are in the form:
277 <tcti-name>:<tcti-option-config>
279 Specifying an empty string for either the <tcti-name> or <tcti-op‐
281 tion-config> results in the default being used for that portion respec‐
282 tively.
283 TCTI Defaults
285 When a TCTI is not specified, the default TCTI is searched for using
286 dlopen(3) semantics. The tools will search for tabrmd, device and
287 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
288 what TCTI will be chosen as the default by using the -v option to print
289 the version information. The “default-tcti” key-value pair will indi‐
290 cate which of the aforementioned TCTIs is the default.
291 Custom TCTIs
293 Any TCTI that implements the dynamic TCTI interface can be loaded. The
294 tools internally use dlopen(3), and the raw tcti-name value is used for
295 the lookup. Thus, this could be a path to the shared library, or a li‐
296 brary name as understood by dlopen(3) semantics.
297
299 This collection of options are used to configure the various known TCTI
300 modules available:
301 • device: For the device TCTI, the TPM character device file for use by
303 the device TCTI can be specified. The default is /dev/tpm0.
304 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
306 vice:/dev/tpm0”
307 • mssim: For the mssim TCTI, the domain name or IP address and port
309 number used by the simulator can be specified. The default are
310 127.0.0.1 and 2321.
311 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
313 TI=“mssim:host=localhost,port=2321”
314 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
316 ries of simple key value pairs separated by a `,' character. Each
317 key and value string are separated by a `=' character.
318 • TCTI abrmd supports two keys:
320 1. `bus_name' : The name of the tabrmd service on the bus (a
322 string).
323 2. `bus_type' : The type of the dbus instance (a string) limited to
325 `session' and `system'.
326 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
328 ample.FooBar:
329 \--tcti=tabrmd:bus_name=com.example.FooBar
331 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
333 sion:
334 \--tcti:bus_type=session
336 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
338 ules. # EXAMPLES
339 Start a trial session and save the session data to a file
341 tpm2_startauthsession -S mysession.ctx
342 Start a policy session and save the session data to a file
344 tpm2_startauthsession --policy-session -S mysession.ctx
345 Start an encrypted and bound policy session and save the session data to a
347 file
348 tpm2_createprimary -c primary.ctx
349 tpm2_startauthsession --policy-session -c primary.ctx -S mysession.ctx
350
352 Tools can return any of the following codes:
353 • 0 - Success.
355 • 1 - General non-specific error.
357 • 2 - Options handling error.
359 • 3 - Authentication error.
361 • 4 - TCTI related error.
363 • 5 - Non supported scheme. Applicable to tpm2_testparams.
365
367 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
368
370 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
371tpm2-tools tpm2_startauthsession(1)