1tpm2_changepps(1) General Commands Manual tpm2_changepps(1)
2
6 tpm2_changepps(1) - Replaces the active platform primary seed with a
7 new one generated off the TPM2 RNG.
8
10 tpm2_changepps [OPTIONS]
11
13 tpm2_changepps(1) - Replaces the active platform primary seed with a
14 new one generated off the TPM2 RNG. The Transient and Persistent ob‐
15 jects under the platform hierarchy are lost whilst retaining the NV ob‐
16 jects.
17
19 • -p, --auth specifies the AUTH for the platform. hierarchy.
20 • --cphash=FILE
22 File path to record the hash of the command parameters. This is com‐
24 monly termed as cpHash. NOTE: When this option is selected, The tool
25 will not actually execute the command, it simply returns a cpHash,
26 unless rphash is also required.
27 • --rphash=FILE
29 File path to record the hash of the response parameters. This is
31 commonly termed as rpHash.
32 • -S, --session=FILE:
34 The session created using tpm2_startauthsession. This can be used to
36 specify an auxiliary session for auditing and or encryption/decryp‐
37 tion of the parameters.
38 References
41 Authorization for use of an object in TPM2.0 can come in 3 different
42 forms: 1. Password 2. HMAC 3. Sessions
43 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
45 fied”.
46 Passwords
48 Passwords are interpreted in the following forms below using prefix
49 identifiers.
50 Note: By default passwords are assumed to be in the string form when
52 they do not have a prefix.
53 String
55 A string password, specified by prefix “str:” or it’s absence (raw
56 string without prefix) is not interpreted, and is directly used for au‐
57 thorization.
58 Examples
60 foobar
61 str:foobar
62 Hex-string
64 A hex-string password, specified by prefix “hex:” is converted from a
65 hexidecimal form into a byte array form, thus allowing passwords with
66 non-printable and/or terminal un-friendly characters.
67 Example
69 hex:0x1122334455667788
70 File
72 A file based password, specified be prefix “file:” should be the path
73 of a file containing the password to be read by the tool or a “-” to
74 use stdin. Storing passwords in files prevents information leakage,
75 passwords passed as options can be read from the process list or common
76 shell history features.
77 Examples
79 # to use stdin and be prompted
80 file:-
81 # to use a file from a path
83 file:path/to/password/file
84 # to echo a password via stdin:
86 echo foobar | tpm2_tool -p file:-
87 # to use a bash here-string via stdin:
89 tpm2_tool -p file:- <<< foobar
91 Sessions
93 When using a policy session to authorize the use of an object, prefix
94 the option argument with the session keyword. Then indicate a path to
95 a session file that was created with tpm2_startauthsession(1). Option‐
96 ally, if the session requires an auth value to be sent with the session
97 handle (eg policy password), then append a + and a string as described
98 in the Passwords section.
99 Examples
101 To use a session context file called session.ctx.
102 session:session.ctx
104 To use a session context file called session.ctx AND send the authvalue
106 mypassword.
107 session:session.ctx+mypassword
109 To use a session context file called session.ctx AND send the HEX auth‐
111 value 0x11223344.
112 session:session.ctx+hex:11223344
114 PCR Authorizations
116 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
117 language. The PCR minilanguage is as follows:
118 <pcr-spec>=<raw-pcr-file>
119 The PCR spec is documented in in the section “PCR bank specifiers”.
121 The raw-pcr-file is an optional argument that contains the output of
123 the raw PCR contents as returned by tpm2_pcrread(1).
124 PCR bank specifiers (pcr.md)
126 Examples
128 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
129 er of:
130 pcr:sha256:0,1,2,3
132 specifying AUTH.
134
136 The TCTI or “Transmission Interface” is the communication mechanism
137 with the TPM. TCTIs can be changed for communication with TPMs across
138 different mediums.
139 To control the TCTI, the tools respect:
141 1. The command line option -T or --tcti
143 2. The environment variable: TPM2TOOLS_TCTI.
145 Note: The command line option always overrides the environment vari‐
147 able.
148 The current known TCTIs are:
150 • tabrmd - The resource manager, called tabrmd
152 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
153 abrmd as a tcti name are synonymous.
154 • mssim - Typically used for communicating to the TPM software simula‐
156 tor.
157 • device - Used when talking directly to a TPM device file.
159 • none - Do not initalize a connection with the TPM. Some tools allow
161 for off-tpm options and thus support not using a TCTI. Tools that do
162 not support it will error when attempted to be used without a TCTI
163 connection. Does not support ANY options and MUST BE presented as
164 the exact text of “none”.
165 The arguments to either the command line option or the environment
167 variable are in the form:
168 <tcti-name>:<tcti-option-config>
170 Specifying an empty string for either the <tcti-name> or <tcti-op‐
172 tion-config> results in the default being used for that portion respec‐
173 tively.
174 TCTI Defaults
176 When a TCTI is not specified, the default TCTI is searched for using
177 dlopen(3) semantics. The tools will search for tabrmd, device and
178 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
179 what TCTI will be chosen as the default by using the -v option to print
180 the version information. The “default-tcti” key-value pair will indi‐
181 cate which of the aforementioned TCTIs is the default.
182 Custom TCTIs
184 Any TCTI that implements the dynamic TCTI interface can be loaded. The
185 tools internally use dlopen(3), and the raw tcti-name value is used for
186 the lookup. Thus, this could be a path to the shared library, or a li‐
187 brary name as understood by dlopen(3) semantics.
188
190 This collection of options are used to configure the various known TCTI
191 modules available:
192 • device: For the device TCTI, the TPM character device file for use by
194 the device TCTI can be specified. The default is /dev/tpm0.
195 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
197 vice:/dev/tpm0”
198 • mssim: For the mssim TCTI, the domain name or IP address and port
200 number used by the simulator can be specified. The default are
201 127.0.0.1 and 2321.
202 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
204 TI=“mssim:host=localhost,port=2321”
205 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
207 ries of simple key value pairs separated by a `,' character. Each
208 key and value string are separated by a `=' character.
209 • TCTI abrmd supports two keys:
211 1. `bus_name' : The name of the tabrmd service on the bus (a
213 string).
214 2. `bus_type' : The type of the dbus instance (a string) limited to
216 `session' and `system'.
217 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
219 ample.FooBar:
220 \--tcti=tabrmd:bus_name=com.example.FooBar
222 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
224 sion:
225 \--tcti:bus_type=session
227 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
229 ules.
230
232 Change the platform primary seed where the platform auth is NULL.
233 tpm2_changepps
234
236 Tools can return any of the following codes:
237 • 0 - Success.
239 • 1 - General non-specific error.
241 • 2 - Options handling error.
243 • 3 - Authentication error.
245 • 4 - TCTI related error.
247 • 5 - Non supported scheme. Applicable to tpm2_testparams.
249
251 It expects a session to be already established via tpm2_startauthses‐
252 sion(1) and requires one of the following:
253 • direct device access
255 • extended session support with tpm2-abrmd.
257 Without it, most resource managers will not save session state between
259 command invocations.
260
262 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
263
265 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
266tpm2-tools tpm2_changepps(1)