1tpm2_changeeps(1) General Commands Manual tpm2_changeeps(1)
2
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 Specifies the AUTH for the platform. hierarchy.
22 • --cphash=FILE
24 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 • --rphash=FILE
31 File path to record the hash of the response parameters. This is
33 commonly termed as rpHash.
34 • -S, --session=FILE:
36 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 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
47 fied”.
48 Passwords
50 Passwords are interpreted in the following forms below using prefix
51 identifiers.
52 Note: By default passwords are assumed to be in the string form when
54 they do not have a prefix.
55 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 Examples
62 foobar
63 str:foobar
64 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 Example
71 hex:1122334455667788
72 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 Examples
81 # to use stdin and be prompted
82 file:-
83 # to use a file from a path
85 file:path/to/password/file
86 # to echo a password via stdin:
88 echo foobar | tpm2_tool -p file:-
89 # to use a bash here-string via stdin:
91 tpm2_tool -p file:- <<< foobar
93 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 Examples
103 To use a session context file called session.ctx.
104 session:session.ctx
106 To use a session context file called session.ctx AND send the authvalue
108 mypassword.
109 session:session.ctx+mypassword
111 To use a session context file called session.ctx AND send the HEX auth‐
113 value 0x11223344.
114 session:session.ctx+hex:11223344
116 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 The PCR spec is documented in in the section “PCR bank specifiers”.
123 The raw-pcr-file is an optional argument that contains the output of
125 the raw PCR contents as returned by tpm2_pcrread(1).
126 PCR bank specifiers (pcr.md)
128 Examples
130 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
131 er of:
132 pcr:sha256:0,1,2,3
134 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 To control the TCTI, the tools respect:
143 1. The command line option -T or --tcti
145 2. The environment variable: TPM2TOOLS_TCTI.
147 Note: The command line option always overrides the environment vari‐
149 able.
150 The current known TCTIs are:
152 • 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 • mssim - Typically used for communicating to the TPM software simula‐
158 tor.
159 • device - Used when talking directly to a TPM device file.
161 • 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 The arguments to either the command line option or the environment
169 variable are in the form:
170 <tcti-name>:<tcti-option-config>
172 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
199 vice:/dev/tpm0”
200 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
206 TI=“mssim:host=localhost,port=2321”
207 • 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 • TCTI abrmd supports two keys:
213 1. `bus_name' : The name of the tabrmd service on the bus (a
215 string).
216 2. `bus_type' : The type of the dbus instance (a string) limited to
218 `session' and `system'.
219 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
221 ample.FooBar:
222 \--tcti=tabrmd:bus_name=com.example.FooBar
224 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
226 sion:
227 \--tcti:bus_type=session
229 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 • 0 - Success.
241 • 1 - General non-specific error.
243 • 2 - Options handling error.
245 • 3 - Authentication error.
247 • 4 - TCTI related error.
249 • 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 • direct device access
257 • extended session support with tpm2-abrmd.
259 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.linuxfoundation.org/mailman/listin‐
268 fo/tpm2)
269tpm2-tools tpm2_changeeps(1)