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
20         · o for TPM_RH_OWNER
21
22         · p 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
54       · ARGUMENT  the  command line argument specifies the NV index or offset
55         number.
56
57   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

299   Read 32 bytes from an index starting at offset 0
300              tpm2_nvdefine -Q  1 -C o -s 32 -a "ownerread|policywrite|ownerwrite"
301
302              echo "please123abc" > nv.test_w
303
304              tpm2_nvwrite -Q   $nv_test_index -C o -i nv.test_w
305
306              tpm2_nvread -Q  1 -C o -s 32 -o 0
307

Returns

309       Tools can return any of the following codes:
310
311       · 0 - Success.
312
313       · 1 - General non-specific error.
314
315       · 2 - Options handling error.
316
317       · 3 - Authentication error.
318
319       · 4 - TCTI related error.
320
321       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
322

BUGS

324       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
325

HELP

327       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
328
329
330
331tpm2-tools                                                      tpm2_nvread(1)
Impressum