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

NAME

6       tpm2_policyauthorizenv(1)  - Allows for mutable policies by referencing
7       to a policy from an NV index.
8

SYNOPSIS

10       tpm2_policyauthorizenv [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_policyauthorizenv(1) - This command allows for policies to  change
14       by referencing the authorization policy written to an NV index.  The NV
15       index containing the authorization policy should remain  readable  even
16       for trial session.  The index can be specified as raw handle or an off‐
17       set value to the nv handle range "TPM2_HR_NV_INDEX".
18

OPTIONS

20       · -C, --hierarchy=OBJECT:
21         Specifies the hierarchy used to authorize.  Supported options are:
22
23         · o for TPM_RH_OWNER
24
25         · p for TPM_RH_PLATFORM
26
27         · <num> where a hierarchy handle or nv-index may be used.
28
29         When -C isn't explicitly passed the index handle will be used to  au‐
30         thorize  against  the  index.  The index auth value is set via the -p
31         option to tpm2_nvdefine(1).
32
33       · -P, --auth=AUTH:
34
35         Specifies the authorization value for the hierarchy.
36
37       · -L, --policy=FILE:
38
39         File to save the policy digest.
40
41       · -S, --session=FILE:
42
43         The policy session file generated via the  -S  option  to  tpm2_star‐
44         tauthsession(1).
45
46   References

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

173       Create  a  policypassword  and  write the policy digest to an NV Index.
174       Build a policyauthorizenv policy referencing the NV index  in  a  trial
175       session.   The  resultant policy digest is then used in creation of ob‐
176       jects.
177
178       In a policy authorization session, first satisfy the policy written  to
179       the  NV  index.  Then run the policyauthorizenv which satisfies the au‐
180       thorization for the object.
181
182   Define the test NV Index to store the auth policy
183              nv_test_index=0x01500001
184              tpm2_nvdefine -C o -p nvpass $nv_test_index -a "authread|authwrite" -s 34
185
186   Define the auth policy
187              tpm2_startauthsession -S session.ctx
188              tpm2_policypassword -S session.ctx -L policy.pass
189              tpm2_flushcontext session.ctx
190
191   Write the auth policy to the NV Index
192              echo "000b" | xxd -p -r | cat - policy.pass | \
193              tpm2_nvwrite -C $nv_test_index -P nvpass $nv_test_index -i-
194
195   Define the policyauthorizenv
196              tpm2_startauthsession -S session.ctx
197              tpm2_policyauthorizenv -S session.ctx -C $nv_test_index -P nvpass \
198              -L policyauthorizenv.1500001 $nv_test_index
199              tpm2_flushcontext session.ctx
200
201   Create and load a sealing object with auth policy =
202       policyauthorizenv
203
204              tpm2_createprimary -C o -c prim.ctx
205
206              echo "secretdata" | \
207              tpm2_create -C prim.ctx -u key.pub -r key.priv \
208              -a "fixedtpm|fixedparent|adminwithpolicy" -L policyauthorizenv.1500001 -i-
209
210              tpm2_load -C prim.ctx -u key.pub -r key.priv -c key.ctx
211
212   Satisfy the auth policy stored in the NV Index and thus
213       policyauthorizenv
214
215              tpm2_startauthsession -S session.ctx --policy-session
216              tpm2_policypassword -S session.ctx
217              tpm2_policyauthorizenv -S session.ctx -C $nv_test_index -P nvpass $nv_test_index
218              tpm2_unseal -c key.ctx -p session:session.ctx
219              tpm2_flushcontext session.ctx
220

Returns

222       Tools can return any of the following codes:
223
224       · 0 - Success.
225
226       · 1 - General non-specific error.
227
228       · 2 - Options handling error.
229
230       · 3 - Authentication error.
231
232       · 4 - TCTI related error.
233
234       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
235

Limitations

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

BUGS

248       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
249

HELP

251       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
252
253
254
255tpm2-tools                                           tpm2_policyauthorizenv(1)
Impressum