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

NAME

6       tpm2_nvread(1) - Read the data stored in a Non-Volatile (NV)s index.
7

SYNOPSIS

9       tpm2_nvread [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_nvread(1)  -  Read  the data stored in a Non-Volatile (NV)s index.
13       The index can be specified as raw handle or an offset value to  the  nv
14       handle range “TPM2_HR_NV_INDEX”.
15

OPTIONS

17-C, --hierarchy=OBJECT:
18         Specifies the hierarchy used to authorize.  Supported options are:
19
20o for TPM_RH_OWNER
21
22p for TPM_RH_PLATFORM
23
24<num> where a hierarchy handle or nv-index may be used.
25
26         When  -C isn’t explicitly passed the index handle will be used to au‐
27         thorize against the index.  The index auth value is set  via  the  -p
28         option to tpm2_nvdefine(1).
29
30-o, --output=FILE:
31
32         File to write data
33
34-P, --auth=AUTH:
35
36         Specifies the authorization value for the hierarchy.
37
38-s, --size=NATURAL_NUMBER:
39
40         Specifies  the  size  of data to be read in bytes, starting from 0 if
41         offset is not specified.  If not specified, the size of the  data  as
42         reported by the public portion of the index will be used.
43
44--offset=NATURAL_NUMBER:
45
46         The offset within the NV index to start reading from.
47
48--cphash=FILE
49
50         File path to record the hash of the command parameters.  This is com‐
51         monly termed as cpHash.  NOTE: When this option is selected, The tool
52         will  not  actually  execute the command, it simply returns a cpHash,
53         unless rphash is also required.
54
55--rphash=FILE
56
57         File path to record the hash of the  response  parameters.   This  is
58         commonly termed as rpHash.
59
60-n, --name=FILE:
61
62         The  name of the NV index that must be provided when only calculating
63         the cpHash without actually dispatching the command to the TPM.
64
65-S, --session=FILE:
66
67         The session created using tpm2_startauthsession.  This can be used to
68         specify  an  auxiliary session for auditing and or encryption/decryp‐
69         tion of the parameters.
70
71ARGUMENT the command line argument specifies the NV index  or  offset
72         number.
73
74   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

316   Read 32 bytes from an index starting at offset 0
317              tpm2_nvdefine -C o -s 32 -a "ownerread|policywrite|ownerwrite" 1
318
319              echo "please123abc" > nv.dat
320
321              tpm2_nvwrite -C o -i nv.dat 1
322
323              tpm2_nvread -C o -s 32 1
324

Returns

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

BUGS

341       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
342

HELP

344       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
345
346
347
348tpm2-tools                                                      tpm2_nvread(1)
Impressum