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

NAME

6       tpm2_changeauth - Changes authorization values for TPM objects.
7

SYNOPSIS

9       tpm2_changeauth [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_changeauth - Configures authorization values for the various hier‐
13       archies, NV indices, transient and persistent objects.
14
15       Note: For non-permanent objects (Transient objects and  Persistent  ob‐
16       jects), copies of the private information (files or persistent handles)
17       created prior to changing auth are not invalidated.
18

OPTIONS

20       Passwords should follow the “password  authorization  formatting  stan‐
21       dards”, see section “Authorization Formatting”.
22
23-c, --object-context=OBJECT:
24
25         The key context object to be used for the operation.
26
27-p, --object-auth=AUTH:
28
29         The old authorization value for the TPM object specified with -c.
30
31-C, --parent-context=OBJECT:
32
33         The  parent object.  This is required if the object for the operation
34         is a transient or persistent object.
35
36-r, --private=FILE: The output file which contains the new  sensitive
37         portion of the object whose auth was being changed.  # Protection De‐
38         tails
39
40       Objects that can move outside of TPM need to  be  protected  (confiden‐
41       tiality  and  integrity).  For instance, transient objects require that
42       TPM protected data (key or seal material) be stored outside of the TPM.
43       This  is seen in tools like tpm2_create(1), where the -r option outputs
44       this protected data.  This blob contains the sensitive portions of  the
45       object.  The sensitive portions of the object are protected by the par‐
46       ent object, using the parent’s symmetric encryption details to  encrypt
47       the sensitive data and HMAC it.
48
49       In-depth details can be found in sections 23 of:
50
51https://trustedcomputinggroup.org/wp-content/up
52         loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
53
54       Notably Figure 20, is relevant, even though it’s specifically referring
55       to duplication blobs, the process is identical.
56
57       If  the  output  is from tpm2_duplicate(1), the output will be slightly
58       different, as described fully in section 23.
59
60--cphash=FILE
61
62         File path to record the hash of the command parameters.  This is com‐
63         monly termed as cpHash.  NOTE: When this option is selected, The tool
64         will not actually execute the command, it simply  returns  a  cpHash,
65         unless rphash is also required.
66
67--rphash=FILE
68
69         File  path  to  record  the hash of the response parameters.  This is
70         commonly termed as rpHash.
71
72-S, --session=FILE:
73
74         The session created using tpm2_startauthsession.  This can be used to
75         specify  an  auxiliary session for auditing and or encryption/decryp‐
76         tion of the parameters.
77
78ARGUMENT the command line argument specifies the AUTH to be  set  for
79         the object specified with -c.
80
81   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

323   Set owner, endorsement and lockout authorizations to newpass
324              tpm2_changeauth -c owner newpass
325              tpm2_changeauth -c endorsement newpass
326              tpm2_changeauth -c lockout newpass
327
328   Change owner, endorsement and lockout authorizations
329              tpm2_changeauth -c o -p newpass newerpass
330              tpm2_changeauth -c e -p newpass newerpass
331              tpm2_changeauth -c l -p newpass newerpass
332
333   Set owner authorization to empty password
334              tpm2_changeauth -c o -p oldpass
335
336   Modify authorization for a loadable transient object
337              tpm2_createprimary -Q -C o -c prim.ctx
338
339              tpm2_create -Q -g sha256 -G aes -u key.pub -r key.priv -C prim.ctx
340
341              tpm2_load -C prim.ctx -u key.pub -r key.priv -n key.name -c key.ctx
342
343              tpm2_changeauth -c key.ctx -C prim.ctx -r key.priv newkeyauth
344
345   Modify authorization for a NV Index
346       Requires Extended Session Support.
347
348              tpm2_startauthsession -S session.ctx
349
350              tpm2_policycommandcode -S session.ctx -L policy.nvchange TPM2_CC_NV_ChangeAuth
351              tpm2_flushcontext session.ctx
352
353              NVIndex=0x1500015
354              tpm2_nvdefine   $NVIndex -C o -s 32 -a "authread|authwrite" -L policy.nvchange
355              tpm2_startauthsession \--policy-session -S session.ctx
356
357              tpm2_policycommandcode -S session.ctx -L policy.nvchange TPM2_CC_NV_ChangeAuth
358
359              tpm2_changeauth -p session:session.ctx -c $NVIndex newindexauth
360

Returns

362       Tools can return any of the following codes:
363
364       • 0 - Success.
365
366       • 1 - General non-specific error.
367
368       • 2 - Options handling error.
369
370       • 3 - Authentication error.
371
372       • 4 - TCTI related error.
373
374       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
375

BUGS

377       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
378

HELP

380       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
381       fo/tpm2)
382
383
384
385tpm2-tools                                                  tpm2_changeauth(1)
Impressum