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

NAME

6       tpm2_policylocality(1)  - Restrict TPM object authorization to specific
7       localities.
8

SYNOPSIS

10       tpm2_policylocality [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_policylocality(1) - Restricts TPM object authorization to specific
14       TPM  locality.   Useful  when  you want to allow only specific locality
15       with the TPM object.  A locality indicates the source of  the  command,
16       for example it could be from the application layer or the driver layer,
17       each would have it’s own locality integer.  Localities are hints to the
18       TPM  and  are  enforced by the software communicating to the TPM.  Thus
19       they are not trusted inputs on their own and are implemented  in  plat‐
20       form specific ways.
21
22       As an argument it takes the LOCALITY as an integer or friendly name.
23
24       Localities  are  fixed  to a byte in size and have two representations,
25       locality and extended locality.
26
27       Localities 0 through 4 are the normal locality representation  and  are
28       represented  as  set bit indexes.  Thus locality 0 is indicated by 1<<0
29       and locality 4 is indicated by 1<<4.  Rather then  using  raw  numbers,
30       these  localities can also be specified by the friendly names of: - ze‐
31       ro: locality 0 or 1<<0 - one: locality 1 or 1<<1 - two: locality  2  or
32       1<<2 - three: locality 3 or 1<<3 - four: locality 4 or 1<<4
33
34       Anything from the range 32 - 255 are extended localities.
35

OPTIONS

37-S, --session=FILE:
38
39         A session file from tpm2_startauthsession(1)’s -S option.
40
41-L, --policy=FILE:
42
43         File to save the policy digest.
44
45ARGUMENT the command line argument specifies the locality number.
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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

180       Start  a  policy  session and extend it with a specific locality number
181       (like 3).  Attempts to perform other operations would fail.
182
183   Create an policy restricted by locality 3
184              tpm2_startauthsession -S session.dat
185
186              tpm2_policylocality -S session.dat -L policy.dat three
187
188              tpm2_flushcontext session.dat
189
190   Create the object with auth policy
191              tpm2_createprimary -C o -c prim.ctx
192
193              tpm2_create -C prim.ctx -u sealkey.pub -r sealkey.priv -L policy.dat \
194              -i- <<< "SEALED-SECRET"
195
196   Try unseal operation
197              tpm2_load -C prim.ctx -u sealkey.pub -r sealkey.priv -n sealkey.name \
198              -c sealkey.ctx
199
200              tpm2_startauthsession \--policy-session -S session.dat
201
202              tpm2_policylocality -S session.dat -L policy.dat three
203
204              # Change to locality 3, Note: this operation varies on different platforms
205
206              tpm2_unseal -p session:session.dat -c sealkey.ctx
207
208              tpm2_flushcontext session.dat
209

Returns

211       Tools can return any of the following codes:
212
213       • 0 - Success.
214
215       • 1 - General non-specific error.
216
217       • 2 - Options handling error.
218
219       • 3 - Authentication error.
220
221       • 4 - TCTI related error.
222
223       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
224

Limitations

226       It expects a session to be already established  via  tpm2_startauthses‐
227       sion(1) and requires one of the following:
228
229       • direct device access
230
231       • extended session support with tpm2-abrmd.
232
233       Without  it, most resource managers will not save session state between
234       command invocations.
235

BUGS

237       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
238

HELP

240       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
241       fo/tpm2)
242
243
244
245tpm2-tools                                              tpm2_policylocality(1)
Impressum