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

NAME

6       tpm2_nvsetbits(1) - Bitwise OR bits into a Non-Volatile (NV).
7

SYNOPSIS

9       tpm2_nvsetbits [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_nvsetbits(1)  -  Bitwise OR bits into a Non-Volatile (NV).  The NV
13       index must be of type "bits" which is specified via the "nt" field when
14       creating  the  NV space with tpm2_nvdefine(1).  The index can be speci‐
15       fied as  raw  handle  or  an  offset  value  to  the  NV  handle  range
16       "TPM2_HR_NV_INDEX".
17

OPTIONS

19       · -C, --hierarchy=OBJECT:
20         Specifies the hierarchy used to authorize.  Supported options are:
21
22         · o for TPM_RH_OWNER
23
24         · p 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, --bits=BITS:
37
38         Specifies  the  bit  value as a number to bitwise OR into the current
39         value of the NV index.
40
41       · ARGUMENT the command line argument specifies the NV index  or  offset
42         number.
43
44   References

Context Object Format

46       The  type  of a context object, whether it is a handle or file name, is
47       determined according to the following logic in-order:
48
49       · If the argument is a file path, then the file is loaded as a restored
50         TPM transient object.
51
52       · If the argument is a prefix match on one of:
53
54         · owner: the owner hierarchy
55
56         · platform: the platform hierarchy
57
58         · endorsement: the endorsement hierarchy
59
60         · lockout: the lockout control persistent object
61
62       · If  the  argument argument can be loaded as a number it will be treat
63         as a handle, e.g.  0x81010013 and used directly.OBJECT.
64

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

286   OR 0xbadc0de into an index of 0's
287              tpm2_nvdefine -C o -a "nt=bits|ownerread|policywrite|ownerwrite|writedefine" 1
288
289              tpm2_nvsetbits -C o -i 0xbadc0de 1
290
291              tpm2_nvread -C o 1 | xxd -p | sed s/'^0*'/0x/
292              0xbadc0de
293

Returns

295       Tools can return any of the following codes:
296
297       · 0 - Success.
298
299       · 1 - General non-specific error.
300
301       · 2 - Options handling error.
302
303       · 3 - Authentication error.
304
305       · 4 - TCTI related error.
306
307       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
308

BUGS

310       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
311

HELP

313       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
314
315
316
317tpm2-tools                                                   tpm2_nvsetbits(1)
Impressum