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

NAME

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

SYNOPSIS

10       tpm2_changepps [OPTIONS]
11

DESCRIPTION

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

OPTIONS

19-p, --auth specifies the AUTH for the platform.  hierarchy.
20
21--cphash=FILE
22
23         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
28--rphash=FILE
29
30         File path to record the hash of the  response  parameters.   This  is
31         commonly termed as rpHash.
32
33-S, --session=FILE:
34
35         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
39   References

Authorization Formatting

41       Authorization  for  use  of an object in TPM2.0 can come in 3 different
42       forms: 1.  Password 2.  HMAC 3.  Sessions
43
44       NOTE: "Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
45       fied".
46
47   Passwords
48       Passwords  are  interpreted  in  the following forms below using prefix
49       identifiers.
50
51       Note: By default passwords are assumed to be in the  string  form  when
52       they do not have a prefix.
53
54   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
59   Examples
60              foobar
61              str:foobar
62
63   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
68   Example
69              hex:0x1122334455667788
70
71   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
78   Examples
79              # to use stdin and be prompted
80              file:-
81
82              # to use a file from a path
83              file:path/to/password/file
84
85              # to echo a password via stdin:
86              echo foobar | tpm2_tool -p file:-
87
88              # to use a bash here-string via stdin:
89
90              tpm2_tool -p file:- <<< foobar
91
92   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
100   Examples
101       To use a session context file called session.ctx.
102
103              session:session.ctx
104
105       To use a session context file called session.ctx AND send the authvalue
106       mypassword.
107
108              session:session.ctx+mypassword
109
110       To use a session context file called session.ctx AND send the HEX auth‐
111       value 0x11223344.
112
113              session:session.ctx+hex:11223344
114
115   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
120       The PCR spec is documented in in the section "PCR bank specifiers".
121
122       The raw-pcr-file is an optional the output of the raw PCR  contents  as
123       returned by tpm2_pcrread(1).
124
125       PCR bank specifiers (common/pcr.md)
126
127   Examples
128       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
129       er of:
130
131              pcr:sha256:0,1,2,3
132
133       specifying AUTH.
134

TCTI Configuration

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
140       To control the TCTI, the tools respect:
141
142       1. The command line option -T or --tcti
143
144       2. The environment variable: TPM2TOOLS_TCTI.
145
146       Note: The command line option always overrides  the  environment  vari‐
147       able.
148
149       The current known TCTIs are:
150
151       • 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
155       • mssim  - Typically used for communicating to the TPM software simula‐
156         tor.
157
158       • device - Used when talking directly to a TPM device file.
159
160       • 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
166       The arguments to either the command  line  option  or  the  environment
167       variable are in the form:
168
169       <tcti-name>:<tcti-option-config>
170
171       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
175   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
183   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

TCTI OPTIONS

190       This collection of options are used to configure the various known TCTI
191       modules available:
192
193device: 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
196         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
197         vice:/dev/tpm0"
198
199        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
203         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
204         TI="mssim:host=localhost,port=2321"
205
206        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
210         • TCTI abrmd supports two keys:
211
212           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
213              string).
214
215           2. 'bus_type' : The type of the dbus instance (a string) limited to
216              'session' and 'system'.
217
218         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
219         ample.FooBar:
220
221         \--tcti=tabrmd:bus_name=com.example.FooBar
222
223         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
224         sion:
225
226         \--tcti:bus_type=session
227
228         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
229         ules.
230

EXAMPLES

232   Change the platform primary seed where the platform auth is NULL.
233              tpm2_changepps
234

Returns

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

Limitations

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

BUGS

262       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
263

HELP

265       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
266
267
268
269tpm2-tools                                                   tpm2_changepps(1)
Impressum