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

NAME

6       tpm2_policynv(1) - Evaluates policy authorization by comparing a speci‐
7       fied value against the contents in the specified NV Index.
8

SYNOPSIS

10       tpm2_policynv [OPTIONS] [ARGUMENT] [ARGUMENT]
11

DESCRIPTION

13       tpm2_policynv(1) - This command evaluates policy authorization by  com‐
14       paring the contents written to an NV index against the one specified in
15       the tool options.  The tool takes two arguments  -  (1)  The  NV  index
16       specified  as  raw  handle  or  an  offset value to the nv handle range
17       "TPM2_HR_NV_INDEX" and (2) Comparison operator for magnitude comparison
18       and  or bit test operations.  In the specification the NV index holding
19       the data is called operandA and the data that  the  user  specifies  to
20       compare  is  called operandB.  The comparison operator can be specified
21       as follows: * "eq" if operandA  =  operandB  *  "neq"  if  operandA  !=
22       operandB  *  "sgt"  if signed operandA > signed operandB * "ugt" if un‐
23       signed operandA > unsigned operandB * "slt" if signed operandA < signed
24       operandB  *  "ult"  if unsigned operandA < unsigned operandB * "sge" if
25       signed operandA >= signed operandB * "uge" if unsigned operandA >=  un‐
26       signed operandB * "sle" if signed operandA <= unsigned operandB * "ule"
27       if unsigned operandA <= unsigned operandB * "bs" if  all  bits  set  in
28       operandA  are  set  in  operandB * "bc" if all bits set in operandA are
29       clear in operandB
30

OPTIONS

32       · -C, --hierarchy=OBJECT:
33         Specifies the hierarchy used to authorize.  Supported options are:
34
35         · o for TPM_RH_OWNER
36
37         · p for TPM_RH_PLATFORM
38
39         · <num> where a hierarchy handle or nv-index may be used.
40
41         When -C isn't explicitly passed the index handle will be used to  au‐
42         thorize  against  the  index.  The index auth value is set via the -p
43         option to tpm2_nvdefine(1).
44
45       · -P, --auth=AUTH:
46
47         Specifies the authorization value for the hierarchy.
48
49       · -L, --policy=FILE:
50
51         File to save the policy digest.
52
53       · -S, --session=FILE:
54
55         The policy session file generated via the  -S  option  to  tpm2_star‐
56         tauthsession or saved off of a previous tool run.
57
58       · --offset=NATURAL_NUMBER:
59
60         The  offset  within  the NV index to start comparing at.  The size of
61         the data starting at offset and ending at size of NV index shall  not
62         exceed the size of the operand specified in the options.
63
64       · --cphash=FILE
65
66         File path to record the hash of the command parameters.  This is com‐
67         monly termed as cpHash.  NOTE: When this option is selected, The tool
68         will not actually execute the command, it simply returns a cpHash.
69
70       · -i, --input=FILE:
71
72         Specifies  the  input file with data to compare to NV Index contents.
73         In the standard specification, this is termed as operand or  operandB
74         more  specifically .  It can be specified as a file input or stdin if
75         option value is a "-".
76
77   References

COMMON OPTIONS

79       This collection of options are common to many programs and provide  in‐
80       formation that many users may expect.
81
82       · -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
83         attempts to invoke the manpager for the  tool,  however,  on  failure
84         will  output  a short tool summary.  This is the same behavior if the
85         "man" option argument is specified, however if explicit "man" is  re‐
86         quested,  the  tool  will  provide errors from man on stderr.  If the
87         "no-man" option if specified, or the manpager fails,  the  short  op‐
88         tions will be output to stdout.
89
90         To  successfully use the manpages feature requires the manpages to be
91         installed or on MANPATH, See man(1) for more details.
92
93       · -v, --version: Display version information for this  tool,  supported
94         tctis and exit.
95
96       · -V,  --verbose:  Increase the information that the tool prints to the
97         console during its execution.  When using this option  the  file  and
98         line number are printed.
99
100       · -Q, --quiet: Silence normal tool output to stdout.
101
102       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
103         if an errata fixup needs to be applied to commands sent to  the  TPM.
104         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
105         formation many users may expect.
106

TCTI Configuration

108       The TCTI or "Transmission Interface"  is  the  communication  mechanism
109       with  the TPM.  TCTIs can be changed for communication with TPMs across
110       different mediums.
111
112       To control the TCTI, the tools respect:
113
114       1. The command line option -T or --tcti
115
116       2. The environment variable: TPM2TOOLS_TCTI.
117
118       Note: The command line option always overrides  the  environment  vari‐
119       able.
120
121       The current known TCTIs are:
122
123       · tabrmd      -     The     resource     manager,     called     tabrmd
124         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
125         abrmd as a tcti name are synonymous.
126
127       · mssim  - Typically used for communicating to the TPM software simula‐
128         tor.
129
130       · device - Used when talking directly to a TPM device file.
131
132       · none - Do not initalize a connection with the TPM.  Some tools  allow
133         for off-tpm options and thus support not using a TCTI.  Tools that do
134         not support it will error when attempted to be used  without  a  TCTI
135         connection.   Does  not  support ANY options and MUST BE presented as
136         the exact text of "none".
137
138       The arguments to either the command  line  option  or  the  environment
139       variable are in the form:
140
141       <tcti-name>:<tcti-option-config>
142
143       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
144       tion-config> results in the default being used for that portion respec‐
145       tively.
146
147   TCTI Defaults
148       When  a  TCTI  is not specified, the default TCTI is searched for using
149       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
150       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
151       what TCTI will be chosen as the default by using the -v option to print
152       the  version information.  The "default-tcti" key-value pair will indi‐
153       cate which of the aforementioned TCTIs is the default.
154
155   Custom TCTIs
156       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
157       tools internally use dlopen(3), and the raw tcti-name value is used for
158       the lookup.  Thus, this could be a path to the shared library, or a li‐
159       brary name as understood by dlopen(3) semantics.
160

TCTI OPTIONS

162       This collection of options are used to configure the various known TCTI
163       modules available:
164
165       · device: For the device TCTI, the TPM character device file for use by
166         the device TCTI can be specified.  The default is /dev/tpm0.
167
168         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
169         vice:/dev/tpm0"
170
171       · mssim: For the mssim TCTI, the domain name or  IP  address  and  port
172         number  used  by  the  simulator  can  be specified.  The default are
173         127.0.0.1 and 2321.
174
175         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
176         TI="mssim:host=localhost,port=2321"
177
178       · abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
179         ries of simple key value pairs separated by a  ','  character.   Each
180         key and value string are separated by a '=' character.
181
182         · TCTI abrmd supports two keys:
183
184           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
185              string).
186
187           2. 'bus_type' : The type of the dbus instance (a string) limited to
188              'session' and 'system'.
189
190         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
191         ample.FooBar:
192
193         \--tcti=tabrmd:bus_name=com.example.FooBar
194
195         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
196         sion:
197
198         \--tcti:bus_type=session
199
200         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
201         ules.
202

EXAMPLES

204       Test if NV index content value is equal to an input number.  To do this
205       we  first  create  an  NV  index of size 1 byte and write a value.  Eg.
206       0xAA.  Next we attempt to create a policy that  becomes  valid  if  the
207       equality  comparison  operation of the NV index content against the one
208       specified in the tool options.
209
210   Define the test NV Index and write the value 0xAA to it
211              nv_test_index=0x01500001
212              tpm2_nvdefine -C o -p nvpass $nv_test_index -a "authread|authwrite" -s 1
213              echo "aa" | xxd -r -p | tpm2_nvwrite -P nvpass -i- $nv_test_index
214
215   Attempt defining policynv with wrong comparison value specified in
216       options.
217
218              tpm2_startauthsession -S session.ctx --policy-session
219              ### This should fail
220              echo 0xBB | tpm2_policynv -S session.ctx -L policy.nv -i- 0x1500001 eq -P nvpass
221              tpm2_flushcontext session.ctx
222
223   Attempt defining policynv with right comparison value specified in
224       options.
225
226              tpm2_startauthsession -S session.ctx --policy-session
227              ### This should pass
228              echo 0xAA | tpm2_policynv -S session.ctx -L policy.nv -i- 0x1500001 eq -P nvpass
229              tpm2_flushcontext session.ctx
230

Returns

232       Tools can return any of the following codes:
233
234       · 0 - Success.
235
236       · 1 - General non-specific error.
237
238       · 2 - Options handling error.
239
240       · 3 - Authentication error.
241
242       · 4 - TCTI related error.
243
244       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
245

Limitations

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

BUGS

258       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
259

HELP

261       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
262
263
264
265tpm2-tools                                                    tpm2_policynv(1)
Impressum