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

NAME

6       tpm2_nvextend(1) - Extend an Non-Volatile (NV) index like it was a PCR.
7

SYNOPSIS

9       tpm2_nvextend [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_nvextend(1) - Extend an Non-Volatile (NV) index like it was a PCR.
13       The NV index must be of type “extend” which is specified via  the  “nt”
14       field  when creating the NV space with tpm2_nvdefine(1).  The index can
15       be specified as raw handle or an offset value to the  NV  handle  range
16       “TPM2_HR_NV_INDEX” as an argument.
17

OPTIONS

19-C, --hierarchy=OBJECT:
20         Specifies the hierarchy used to authorize.  Supported options are:
21
22o for TPM_RH_OWNER
23
24p for TPM_RH_PLATFORM
25
26<num> where a hierarchy handle or nv-index may be used.
27
28         When  -C isn’t explicitly passed the index handle will be used to au‐
29         thorize against the index.  The index auth value is set  via  the  -p
30         option to tpm2_nvdefine(1).
31
32-P, --auth=AUTH:
33
34         Specifies the authorization value for the hierarchy.
35
36-i, --input=FILE:
37
38         Specifies the input file with data to extend to the NV index.
39
40--cphash=FILE
41
42         File path to record the hash of the command parameters.  This is com‐
43         monly termed as cpHash.  NOTE: When this option is selected, The tool
44         will  not  actually  execute the command, it simply returns a cpHash,
45         unless rphash is also required.
46
47--rphash=FILE
48
49         File path to record the hash of the  response  parameters.   This  is
50         commonly termed as rpHash.
51
52-S, --session=FILE:
53
54         The  session  created using tpm2_startauthsession.  Multiple of these
55         can be specified.  For example, you can have one session for auditing
56         and another for encryption/decryption of the parameters.
57
58-n, --name=FILE:
59
60         The  name of the NV index that must be provided when only calculating
61         the cpHash without actually dispatching the command to the TPM.
62
63ARGUMENT the command line argument specifies the NV index  or  offset
64         number.
65
66   References

Context Object Format

68       The  type  of a context object, whether it is a handle or file name, is
69       determined according to the following logic in-order:
70
71       • If the argument is a file path, then the file is loaded as a restored
72         TPM transient object.
73
74       • If the argument is a prefix match on one of:
75
76         • owner: the owner hierarchy
77
78         • platform: the platform hierarchy
79
80         • endorsement: the endorsement hierarchy
81
82         • lockout: the lockout control persistent object
83
84       • If  the  argument argument can be loaded as a number it will be treat
85         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
86

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

308   OR 0xbadc0de into an index of 0’s
309              tpm2_nvdefine -C o -a "nt=extend|ownerread|policywrite|ownerwrite|writedefine" 1
310
311              echo 'my data' | tpm2_nvextend -C o -i- 1
312
313              tpm2_nvread -C o 1 | xxd -p -c32
314              db7472e3fe3309b011ec11565bce4ea6668cc8ecdef7e6fdcda5206687af3f43
315

Returns

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

BUGS

332       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
333

HELP

335       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
336       fo/tpm2)
337
338
339
340tpm2-tools                                                    tpm2_nvextend(1)
Impressum