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

NAME

6       tpm2_ticket(1)  -  Enables  policy  authorization by verifying a ticket
7       that represents a validated authorization that had an  expiration  time
8       associated with it.
9

SYNOPSIS

11       tpm2_ticket [OPTIONS]
12

DESCRIPTION

14       tpm2_ticket(1)  -  Enables  policy  authorization by verifying a ticket
15       that represents a validated authorization that had an  expiration  time
16       associated with it.
17

OPTIONS

19       • -L, --policy=FILE:
20
21         File to save the compounded policy digest.
22
23       • -S, --session=FILE:
24
25         The  policy  session  file  generated via the -S option to tpm2_star‐
26         tauthsession(1).
27
28       • -n, --name=FILE:
29
30         Name of the object that validated the authorization.
31
32       • --ticket=FILE:
33
34         The ticket file to record the authorization ticket structure.
35
36       • --timeout=FILE:
37
38         The file path to record the timeout structure returned.
39
40       • -q, --qualification=FILE_OR_HEX_STR:
41
42         Optional, the policy qualifier data that the signer can choose to in‐
43         clude in the signature.  Can be either a hex string or path.
44
45   References

COMMON OPTIONS

47       This  collection of options are common to many programs and provide in‐
48       formation that many users may expect.
49
50       • -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
51         attempts  to  invoke  the  manpager for the tool, however, on failure
52         will output a short tool summary.  This is the same behavior  if  the
53         “man”  option argument is specified, however if explicit “man” is re‐
54         quested, the tool will provide errors from man  on  stderr.   If  the
55         “no-man”  option  if  specified, or the manpager fails, the short op‐
56         tions will be output to stdout.
57
58         To successfully use the manpages feature requires the manpages to  be
59         installed or on MANPATH, See man(1) for more details.
60
61       • -v,  --version:  Display version information for this tool, supported
62         tctis and exit.
63
64       • -V, --verbose: Increase the information that the tool prints  to  the
65         console  during  its  execution.  When using this option the file and
66         line number are printed.
67
68       • -Q, --quiet: Silence normal tool output to stdout.
69
70       • -Z, --enable-errata: Enable the application of errata fixups.  Useful
71         if  an  errata fixup needs to be applied to commands sent to the TPM.
72         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
73         formation many users may expect.
74

TCTI Configuration

76       The  TCTI  or  “Transmission  Interface” is the communication mechanism
77       with the TPM.  TCTIs can be changed for communication with TPMs  across
78       different mediums.
79
80       To control the TCTI, the tools respect:
81
82       1. The command line option -T or --tcti
83
84       2. The environment variable: TPM2TOOLS_TCTI.
85
86       Note:  The  command  line option always overrides the environment vari‐
87       able.
88
89       The current known TCTIs are:
90
91       • tabrmd     -     The     resource     manager,     called      tabrmd
92         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
93         abrmd as a tcti name are synonymous.
94
95       • mssim - Typically used for communicating to the TPM software  simula‐
96         tor.
97
98       • device - Used when talking directly to a TPM device file.
99
100       • none  - Do not initalize a connection with the TPM.  Some tools allow
101         for off-tpm options and thus support not using a TCTI.  Tools that do
102         not  support  it  will error when attempted to be used without a TCTI
103         connection.  Does not support ANY options and MUST  BE  presented  as
104         the exact text of “none”.
105
106       The  arguments  to  either  the  command line option or the environment
107       variable are in the form:
108
109       <tcti-name>:<tcti-option-config>
110
111       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
112       tion-config> results in the default being used for that portion respec‐
113       tively.
114
115   TCTI Defaults
116       When a TCTI is not specified, the default TCTI is  searched  for  using
117       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
118       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
119       what TCTI will be chosen as the default by using the -v option to print
120       the version information.  The “default-tcti” key-value pair will  indi‐
121       cate which of the aforementioned TCTIs is the default.
122
123   Custom TCTIs
124       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
125       tools internally use dlopen(3), and the raw tcti-name value is used for
126       the lookup.  Thus, this could be a path to the shared library, or a li‐
127       brary name as understood by dlopen(3) semantics.
128

TCTI OPTIONS

130       This collection of options are used to configure the various known TCTI
131       modules available:
132
133       • device: For the device TCTI, the TPM character device file for use by
134         the device TCTI can be specified.  The default is /dev/tpm0.
135
136         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
137         vice:/dev/tpm0”
138
139       • mssim:  For  the  mssim  TCTI, the domain name or IP address and port
140         number used by the simulator  can  be  specified.   The  default  are
141         127.0.0.1 and 2321.
142
143         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
144         TI=“mssim:host=localhost,port=2321”
145
146       • abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
147         ries  of  simple  key value pairs separated by a `,' character.  Each
148         key and value string are separated by a `=' character.
149
150         • TCTI abrmd supports two keys:
151
152           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
153              string).
154
155           2. `bus_type' : The type of the dbus instance (a string) limited to
156              `session' and `system'.
157
158         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
159         ample.FooBar:
160
161                \--tcti=tabrmd:bus_name=com.example.FooBar
162
163         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
164         sion:
165
166                \--tcti:bus_type=session
167
168         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
169         ules.
170

EXAMPLES

172       Authorize  a TPM operation on an object whose authorization is bound to
173       specific signing authority.
174
175   Create the signing authority and load the verification key
176              openssl genrsa -out private.pem 2048
177
178              openssl rsa -in private.pem -outform PEM -pubout -out public.pem
179
180              tpm2_loadexternal -C o -G rsa -u public.pem -c signing_key.ctx \
181              -n signing_key.name
182
183   Generate signature with the expiry time
184              EXPIRYTIME="FFFFFE0C"
185
186              echo $EXPIRYTIME | xxd -r -p | \
187              openssl dgst -sha256 -sign private.pem -out signature.dat
188
189   Create the policy
190              tpm2_startauthsession -S session.ctx
191
192              tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
193              -c signing_key.ctx -L policy.signed
194
195              tpm2_flushcontext session.ctx
196
197   Create a sealing object
198              tpm2_createprimary -C o -c prim.ctx -Q
199
200              echo "plaintext" > secret.dat
201
202              tpm2_create -u sealing_key.pub -r sealing_key.priv -c sealing_key.ctx \
203              -C prim.ctx -i secret.dat -L policy.signed -Q
204
205   Create ticket-able policy
206              tpm2_startauthsession -S session.ctx --nonce-tpm=nonce.test --policy-session
207
208              { cat nonce.test & echo $EXPIRYTIME | xxd -r -p; } | \
209              openssl dgst -sha256 -sign private.pem -out signature.dat
210
211              tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
212              -c signing_key.ctx -x nonce.test --ticket tic.ket --timeout time.out \
213              -t 0xFFFFFE0C
214
215              tpm2_flushcontext session.ctx
216
217       ##Test with policyticket instead of policysigned
218
219              tpm2_startauthsession -S session.ctx --policy-session
220
221              tpm2_policyticket -S session.ctx -n signing_key.name --ticket tic.ket \
222              --timeout time.out
223
224              tpm2_unseal -p session:session.ctx -c sealing_key.ctx
225

Returns

227       Tools can return any of the following codes:
228
229       • 0 - Success.
230
231       • 1 - General non-specific error.
232
233       • 2 - Options handling error.
234
235       • 3 - Authentication error.
236
237       • 4 - TCTI related error.
238
239       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
240

Limitations

242       It expects a session to be already established  via  tpm2_startauthses‐
243       sion(1) and requires one of the following:
244
245       • direct device access
246
247       • extended session support with tpm2-abrmd.
248
249       Without  it, most resource managers will not save session state between
250       command invocations.
251

BUGS

253       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
254

HELP

256       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
257
258
259
260tpm2-tools                                                      tpm2_ticket(1)