1tpm2_changeeps(1) General Commands Manual tpm2_changeeps(1)
2
3
4
6 tpm2_changeeps(1) - Replaces the active endorsement primary seed with a
7 new one generated off the TPM2 RNG.
8
10 tpm2_changeeps [OPTIONS]
11
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
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
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
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
192 This collection of options are used to configure the various known TCTI
193 modules available:
194
195 • device: 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
234 Change the endorsement primary seed where the platform auth is NULL.
235 tpm2_changeeps
236
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
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
264 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
265
267 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
268
269
270
271tpm2-tools tpm2_changeeps(1)