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

NAME

6       tpm2_nvundefine(1) - Delete a Non-Volatile (NV) index.
7

SYNOPSIS

9       tpm2_nvundefine [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_nvundefine(1)  - Deletes a Non-Volatile (NV) index that was previ‐
13       ously defined with tpm2_nvdefine(1).  The index is specified as an  ar‐
14       gument.  It can be specified as raw handle or an offset value to the nv
15       handle range “TPM2_HR_NV_INDEX”.
16
17       The tool is also capable of deleting  NV  indices  with  attribute  TP‐
18       MA_NV_POLICY_DELETE,  and  the tool uses this attribute for the default
19       hierarchy to select when -C is missing.  The default value  for  -C  is
20       the  “owner”  hierarchy  when TPMA_NV_POLICY_DELETE is clear and “plat‐
21       form” when TPMA_NV_POLICY_DELETE is set.
22

OPTIONS

24       • -C, --hierarchy=OBJECT:
25         Specifies the hierarchy used to authorize.  Supported options are:
26
27         • o for TPM_RH_OWNER
28
29         • p for TPM_RH_PLATFORM
30
31         • <num> where a hierarchy handle may be specified.
32
33       • -P, --auth=AUTH:
34
35         Specifies the authorization value for the hierarchy.
36
37       • -S, --session=POLICY_SESSION:
38
39         Specify a policy session to use when the NV index has  attribute  TP‐
40         MA_NV_POLICY_DELETE set.
41
42       • --cphash=FILE
43
44         File path to record the hash of the command parameters.  This is com‐
45         monly termed as cpHash.  NOTE: When this option is selected, The tool
46         will not actually execute the command, it simply returns a cpHash.
47
48       • ARGUMENT  the  command line argument specifies the NV index or offset
49         number.
50
51   References

Context Object Format

53       The type of a context object, whether it is a handle or file  name,  is
54       determined according to the following logic in-order:
55
56       • If the argument is a file path, then the file is loaded as a restored
57         TPM transient object.
58
59       • If the argument is a prefix match on one of:
60
61         • owner: the owner hierarchy
62
63         • platform: the platform hierarchy
64
65         • endorsement: the endorsement hierarchy
66
67         • lockout: the lockout control persistent object
68
69       • If the argument argument can be loaded as a number it will  be  treat
70         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
71

Authorization Formatting

73       Authorization  for  use  of an object in TPM2.0 can come in 3 different
74       forms: 1.  Password 2.  HMAC 3.  Sessions
75
76       NOTE: “Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
77       fied”.
78
79   Passwords
80       Passwords  are  interpreted  in  the following forms below using prefix
81       identifiers.
82
83       Note: By default passwords are assumed to be in the  string  form  when
84       they do not have a prefix.
85
86   String
87       A  string  password,  specified  by  prefix “str:” or it’s absence (raw
88       string without prefix) is not interpreted, and is directly used for au‐
89       thorization.
90
91   Examples
92              foobar
93              str:foobar
94
95   Hex-string
96       A  hex-string  password, specified by prefix “hex:” is converted from a
97       hexidecimal form into a byte array form, thus allowing  passwords  with
98       non-printable and/or terminal un-friendly characters.
99
100   Example
101              hex:0x1122334455667788
102
103   File
104       A  file  based password, specified be prefix “file:” should be the path
105       of a file containing the password to be read by the tool or  a  “-”  to
106       use  stdin.   Storing  passwords in files prevents information leakage,
107       passwords passed as options can be read from the process list or common
108       shell history features.
109
110   Examples
111              # to use stdin and be prompted
112              file:-
113
114              # to use a file from a path
115              file:path/to/password/file
116
117              # to echo a password via stdin:
118              echo foobar | tpm2_tool -p file:-
119
120              # to use a bash here-string via stdin:
121
122              tpm2_tool -p file:- <<< foobar
123
124   Sessions
125       When  using  a policy session to authorize the use of an object, prefix
126       the option argument with the session keyword.  Then indicate a path  to
127       a session file that was created with tpm2_startauthsession(1).  Option‐
128       ally, if the session requires an auth value to be sent with the session
129       handle  (eg policy password), then append a + and a string as described
130       in the Passwords section.
131
132   Examples
133       To use a session context file called session.ctx.
134
135              session:session.ctx
136
137       To use a session context file called session.ctx AND send the authvalue
138       mypassword.
139
140              session:session.ctx+mypassword
141
142       To use a session context file called session.ctx AND send the HEX auth‐
143       value 0x11223344.
144
145              session:session.ctx+hex:11223344
146
147   PCR Authorizations
148       You can satisfy a PCR policy using the “pcr:” prefix and the PCR  mini‐
149       language.       The     PCR     minilanguage     is     as     follows:
150       <pcr-spec>=<raw-pcr-file>
151
152       The PCR spec is documented in in the section “PCR bank specifiers”.
153
154       The raw-pcr-file is an optional argument that contains  the  output  of
155       the raw PCR contents as returned by tpm2_pcrread(1).
156
157       PCR bank specifiers (pcr.md)
158
159   Examples
160       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
161       er of:
162
163              pcr:sha256:0,1,2,3
164
165       specifying AUTH.
166

COMMON OPTIONS

168       This collection of options are common to many programs and provide  in‐
169       formation that many users may expect.
170
171       • -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
172         attempts to invoke the manpager for the  tool,  however,  on  failure
173         will  output  a short tool summary.  This is the same behavior if the
174         “man” option argument is specified, however if explicit “man” is  re‐
175         quested,  the  tool  will  provide errors from man on stderr.  If the
176         “no-man” option if specified, or the manpager fails,  the  short  op‐
177         tions will be output to stdout.
178
179         To  successfully use the manpages feature requires the manpages to be
180         installed or on MANPATH, See man(1) for more details.
181
182       • -v, --version: Display version information for this  tool,  supported
183         tctis and exit.
184
185       • -V,  --verbose:  Increase the information that the tool prints to the
186         console during its execution.  When using this option  the  file  and
187         line number are printed.
188
189       • -Q, --quiet: Silence normal tool output to stdout.
190
191       • -Z, --enable-errata: Enable the application of errata fixups.  Useful
192         if an errata fixup needs to be applied to commands sent to  the  TPM.
193         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
194         formation many users may expect.
195

TCTI Configuration

197       The TCTI or “Transmission Interface”  is  the  communication  mechanism
198       with  the TPM.  TCTIs can be changed for communication with TPMs across
199       different mediums.
200
201       To control the TCTI, the tools respect:
202
203       1. The command line option -T or --tcti
204
205       2. The environment variable: TPM2TOOLS_TCTI.
206
207       Note: The command line option always overrides  the  environment  vari‐
208       able.
209
210       The current known TCTIs are:
211
212       • tabrmd      -     The     resource     manager,     called     tabrmd
213         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
214         abrmd as a tcti name are synonymous.
215
216       • mssim  - Typically used for communicating to the TPM software simula‐
217         tor.
218
219       • device - Used when talking directly to a TPM device file.
220
221       • none - Do not initalize a connection with the TPM.  Some tools  allow
222         for off-tpm options and thus support not using a TCTI.  Tools that do
223         not support it will error when attempted to be used  without  a  TCTI
224         connection.   Does  not  support ANY options and MUST BE presented as
225         the exact text of “none”.
226
227       The arguments to either the command  line  option  or  the  environment
228       variable are in the form:
229
230       <tcti-name>:<tcti-option-config>
231
232       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
233       tion-config> results in the default being used for that portion respec‐
234       tively.
235
236   TCTI Defaults
237       When  a  TCTI  is not specified, the default TCTI is searched for using
238       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
239       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
240       what TCTI will be chosen as the default by using the -v option to print
241       the  version information.  The “default-tcti” key-value pair will indi‐
242       cate which of the aforementioned TCTIs is the default.
243
244   Custom TCTIs
245       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
246       tools internally use dlopen(3), and the raw tcti-name value is used for
247       the lookup.  Thus, this could be a path to the shared library, or a li‐
248       brary name as understood by dlopen(3) semantics.
249

TCTI OPTIONS

251       This collection of options are used to configure the various known TCTI
252       modules available:
253
254       • device: For the device TCTI, the TPM character device file for use by
255         the device TCTI can be specified.  The default is /dev/tpm0.
256
257         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
258         vice:/dev/tpm0”
259
260       • mssim: For the mssim TCTI, the domain name or  IP  address  and  port
261         number  used  by  the  simulator  can  be specified.  The default are
262         127.0.0.1 and 2321.
263
264         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
265         TI=“mssim:host=localhost,port=2321”
266
267       • abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
268         ries of simple key value pairs separated by a  `,'  character.   Each
269         key and value string are separated by a `=' character.
270
271         • TCTI abrmd supports two keys:
272
273           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
274              string).
275
276           2. `bus_type' : The type of the dbus instance (a string) limited to
277              `session' and `system'.
278
279         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
280         ample.FooBar:
281
282                \--tcti=tabrmd:bus_name=com.example.FooBar
283
284         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
285         sion:
286
287                \--tcti:bus_type=session
288
289         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
290         ules.
291

EXAMPLES

293   Define an ordinary NV index and delete it
294              tpm2_nvdefine 1
295
296              tpm2_nvundefine 1
297
298   Define an ordinary NV index with attribute TPMA_NV_POLICY_DELETE and delete
299       it
300              tpm2_startauthsession -S s.ctx
301
302              tpm2_policyauthvalue -S s.ctx
303
304              tpm2_policycommandcode -S s.ctx -L policy.dat TPM2_CC_NV_UndefineSpaceSpecial
305
306              tpm2_nvdefine -C p -s 32 \
307                -a "ppread|ppwrite|authread|authwrite|platformcreate|policydelete|write_stclear|read_stclear" \
308                -L policy.dat 1
309
310              tpm2_flushcontext s.ctx
311
312              tpm2_startauthsession --policy-session -S s.ctx
313
314              tpm2_policyauthvalue -S s.ctx
315
316              tpm2_policycommandcode -S s.ctx TPM2_CC_NV_UndefineSpaceSpecial
317
318              tpm2_nvundefine -S s.ctx 1
319

Returns

321       Tools can return any of the following codes:
322
323       • 0 - Success.
324
325       • 1 - General non-specific error.
326
327       • 2 - Options handling error.
328
329       • 3 - Authentication error.
330
331       • 4 - TCTI related error.
332
333       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
334

BUGS

336       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
337

HELP

339       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
340
341
342
343tpm2-tools                                                  tpm2_nvundefine(1)