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

NAME

6       tpm2_changeeps(1) - Replaces the active endorsement primary seed with a
7       new one generated off the TPM2 RNG.
8

SYNOPSIS

10       tpm2_changeeps [OPTIONS]
11

DESCRIPTION

13       tpm2_changeeps(1) - Replaces the active endorsement primary seed with a
14       new  one  generated off the TPM2 RNG.  The Transient and Persistent ob‐
15       jects under the endorsement hierarchy are lost.  This command  requires
16       platform auth.
17

OPTIONS

19-p, --auth=AUTH
20
21         Specifies the AUTH for the platform.  hierarchy.
22
23--cphash=FILE
24
25         File path to record the hash of the command parameters.  This is com‐
26         monly termed as cpHash.  NOTE: When this option is selected, The tool
27         will  not  actually  execute the command, it simply returns a cpHash,
28         unless rphash is also required.
29
30--rphash=FILE
31
32         File path to record the hash of the  response  parameters.   This  is
33         commonly termed as rpHash.
34
35-S, --session=FILE:
36
37         The session created using tpm2_startauthsession.  This can be used to
38         specify an auxiliary session for auditing and  or  encryption/decryp‐
39         tion of the parameters.
40
41   References

Authorization Formatting

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

TCTI Configuration

138       The TCTI or "Transmission Interface"  is  the  communication  mechanism
139       with  the TPM.  TCTIs can be changed for communication with TPMs across
140       different mediums.
141
142       To control the TCTI, the tools respect:
143
144       1. The command line option -T or --tcti
145
146       2. The environment variable: TPM2TOOLS_TCTI.
147
148       Note: The command line option always overrides  the  environment  vari‐
149       able.
150
151       The current known TCTIs are:
152
153       • tabrmd      -     The     resource     manager,     called     tabrmd
154         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
155         abrmd as a tcti name are synonymous.
156
157       • mssim  - Typically used for communicating to the TPM software simula‐
158         tor.
159
160       • device - Used when talking directly to a TPM device file.
161
162       • none - Do not initalize a connection with the TPM.  Some tools  allow
163         for off-tpm options and thus support not using a TCTI.  Tools that do
164         not support it will error when attempted to be used  without  a  TCTI
165         connection.   Does  not  support ANY options and MUST BE presented as
166         the exact text of "none".
167
168       The arguments to either the command  line  option  or  the  environment
169       variable are in the form:
170
171       <tcti-name>:<tcti-option-config>
172
173       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
174       tion-config> results in the default being used for that portion respec‐
175       tively.
176
177   TCTI Defaults
178       When  a  TCTI  is not specified, the default TCTI is searched for using
179       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
180       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
181       what TCTI will be chosen as the default by using the -v option to print
182       the  version information.  The "default-tcti" key-value pair will indi‐
183       cate which of the aforementioned TCTIs is the default.
184
185   Custom TCTIs
186       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
187       tools internally use dlopen(3), and the raw tcti-name value is used for
188       the lookup.  Thus, this could be a path to the shared library, or a li‐
189       brary name as understood by dlopen(3) semantics.
190

TCTI OPTIONS

192       This collection of options are used to configure the various known TCTI
193       modules available:
194
195device: For the device TCTI, the TPM character device file for use by
196         the device TCTI can be specified.  The default is /dev/tpm0.
197
198         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
199         vice:/dev/tpm0"
200
201        mssim: For the mssim TCTI, the domain name or  IP  address  and  port
202         number  used  by  the  simulator  can  be specified.  The default are
203         127.0.0.1 and 2321.
204
205         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
206         TI="mssim:host=localhost,port=2321"
207
208        abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
209         ries of simple key value pairs separated by a  ','  character.   Each
210         key and value string are separated by a '=' character.
211
212         • TCTI abrmd supports two keys:
213
214           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
215              string).
216
217           2. 'bus_type' : The type of the dbus instance (a string) limited to
218              'session' and 'system'.
219
220         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
221         ample.FooBar:
222
223         \--tcti=tabrmd:bus_name=com.example.FooBar
224
225         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
226         sion:
227
228         \--tcti:bus_type=session
229
230         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
231         ules.
232

EXAMPLES

234   Change the endorsement primary seed where the platform auth is NULL.
235              tpm2_changeeps
236

Returns

238       Tools can return any of the following codes:
239
240       • 0 - Success.
241
242       • 1 - General non-specific error.
243
244       • 2 - Options handling error.
245
246       • 3 - Authentication error.
247
248       • 4 - TCTI related error.
249
250       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
251

Limitations

253       It expects a session to be already established  via  tpm2_startauthses‐
254       sion(1) and requires one of the following:
255
256       • direct device access
257
258       • extended session support with tpm2-abrmd.
259
260       Without  it, most resource managers will not save session state between
261       command invocations.
262

BUGS

264       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
265

HELP

267       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
268
269
270
271tpm2-tools                                                   tpm2_changeeps(1)
Impressum