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

NAME

6       tpm2_policyor(1) - logically OR's two policies together.
7

SYNOPSIS

9       tpm2_policyor [OPTIONS]
10

DESCRIPTION

12       tpm2_policyor(1)  -  Generates  a policy_or event with the TPM.  It ex‐
13       pects a session to be already established via tpm2_startauthsession(1).
14       If  the  input  session is a trial session this tool generates a policy
15       digest that compounds two or more input policy digests  such  that  the
16       resulting  policy digest requires at least one of the policy events be‐
17       ing true.  If the input session is real policy session tpm2_policyor(1)
18       authenticates  the  object  successfully  if at least one of the policy
19       events are true.
20

OPTIONS

22       · -L, --policy=FILE:
23
24         File to save the compounded policy digest.
25
26       · -l, --policy-list=POLICY_FILE_LIST:
27
28         The list of files for the policy digests that has  to  be  compounded
29         resulting  in  individual policies being added to final policy digest
30         that can authenticate the object.  The list begins  with  the  policy
31         digest hash alg.
32
33       · -S, --session=FILE:
34
35         The  policy  session  file  generated via the -S option to tpm2_star‐
36         tauthsession(1).
37
38   References

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

165       Creates two sets of PCR data files, one of them being the existing  PCR
166       values and other being a set of PCR values that would result if the PCR
167       were extended with a known value.  Now create two separate  policy  di‐
168       gests, each with one set of the PCR values using tpm2_policypcr(1) tool
169       in trial sessions.  Now build a policy_or with the two PCR  policy  di‐
170       gests as inputs.  Create a sealing object with an authentication policy
171       compounding the 2 policies with tpm2_policyor and seal a  secret.   Un‐
172       sealing with either of the PCR sets should be successful.
173
174   Create two unique pcr policies with corresponding unique sets of
175       pcrs.
176
177   Start with pcr value 0
178              tpm2_pcrreset 23
179
180   PCR1 policy
181              tpm2_startauthsession -S session.ctx
182
183              tpm2_policypcr -S session.ctx -l sha1:23 -L set1.pcr0.policy
184
185              tpm2_flushcontext session.ctx
186
187              rm session.ctx
188
189   PCR2 policy
190              tpm2_pcrextend 23:sha1=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
191
192              tpm2_startauthsession -S session.ctx
193
194              tpm2_policypcr -S session.ctx -l sha1:23 -L set2.pcr0.policy
195
196              tpm2_flushcontext session.ctx
197
198              rm session.ctx
199
200   Create a policyOR resulting from compounding the two unique pcr
201       policies in an OR fashion
202
203              tpm2_startauthsession -S session.ctx
204
205              tpm2_policyor -S session.ctx -L policyOR \
206              -l sha256:set1.pcr0.policy,set2.pcr0.policy
207
208              tpm2_flushcontext session.ctx
209
210              rm session.ctx
211
212   Create a sealing object with auth policyOR created above.
213              tpm2_createprimary -C o -c prim.ctx
214
215              tpm2_create -g sha256 -u sealkey.pub -r sealkey.priv -L policyOR -C prim.ctx \
216              -i- <<< "secretpass"
217
218              tpm2_load -C prim.ctx -c sealkey.ctx -u sealkey.pub -r sealkey.priv
219
220   Attempt unsealing by satisfying the policyOR by satisfying SECOND of
221       the two policies.
222
223              tpm2_startauthsession -S session.ctx --policy-session
224
225              tpm2_policypcr -S session.ctx -l sha1:23
226
227              tpm2_policyor -S session.ctx -L policyOR \
228              -l sha256:set1.pcr0.policy,set2.pcr0.policy
229
230              unsealed=`tpm2_unseal -p session:session.ctx -c sealkey.ctx`
231
232              echo $unsealed
233
234              tpm2_flushcontext session.ctx
235
236              rm session.ctx
237
238   Extend the pcr to emulate tampering of the system software and hence
239       the pcr value.
240
241              tpm2_pcrextend 23:sha1=f1d2d2f924e986ac86fdf7b36c94bcdf32beec15
242
243   Attempt unsealing by trying to satisy the policOR by attempting to
244       satisy one of the two policies.
245
246              tpm2_startauthsession -S session.ctx --policy-session
247
248              tpm2_policypcr -S session.ctx -l sha1:23
249
250   This should fail
251              tpm2_policyor -S session.ctx -L policyOR \
252              -l sha256:set1.pcr0.policy,set2.pcr0.policy
253
254              tpm2_flushcontext session.ctx
255
256              rm session.ctx
257
258   Reset pcr to get back to the first set of pcr value
259              tpm2_pcrreset 23
260
261   Attempt unsealing by satisfying the policyOR by satisfying FIRST of
262       the two policies.
263
264              tpm2_startauthsession -S session.ctx --policy-session
265
266              tpm2_policypcr -S session.ctx -l sha1:23
267
268              tpm2_policyor -S session.ctx -L policyOR \
269              -l sha256:set1.pcr0.policy,set2.pcr0.policy
270
271              unsealed=`tpm2_unseal -p session:session.ctx -c sealkey.ctx`
272
273              echo $unsealed
274
275              tpm2_flushcontext session.ctx
276
277              rm session.ctx
278

Returns

280       Tools can return any of the following codes:
281
282       · 0 - Success.
283
284       · 1 - General non-specific error.
285
286       · 2 - Options handling error.
287
288       · 3 - Authentication error.
289
290       · 4 - TCTI related error.
291
292       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
293

Limitations

295       It  expects  a session to be already established via tpm2_startauthses‐
296       sion(1) and requires one of the following:
297
298       · direct device access
299
300       · extended session support with tpm2-abrmd.
301
302       Without it, most resource managers will not save session state  between
303       command invocations.
304

BUGS

306       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
307

HELP

309       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
310
311
312
313tpm2-tools                                                    tpm2_policyor(1)