1tpm2_policypcr(1) General Commands Manual tpm2_policypcr(1)
2
6 tpm2_policypcr(1) - Create a policy that includes specific PCR values.
7
9 tpm2_policypcr [OPTIONS]
10
12 tpm2_policypcr(1) - Generates a PCR policy event with the TPM. A PCR
13 policy event creates a policy bound to specific PCR values and is use‐
14 ful within larger policies constructed using policyor and policyautho‐
15 rize events. See tpm2_policyor(1) and tpm2_policyauthorize(1) respec‐
16 tively for their usages. The PCR data factored into the policy can be
17 specified in one of 3 ways: 1. A file containing a concatenated list
18 of PCR values as in the output from tpm2_pcrread. 2. Requiring the
19 PCR values be read off the TPM by not specifying a PCR file input. 3.
20 The digest of all the PCR values directly specified as an argument.
21
23 • -L, --policy=FILE:
24 File to save the policy digest.
26 • -f, --pcr=FILE:
28 Optional Path or Name of the file containing expected PCR values for
30 the specified index. Default is to read the current PCRs per the set
31 list.
32 • -l, --pcr-list=PCR:
34 The list of PCR banks and selected PCRs’ ids for each bank.
36 • -S, --session=FILE:
38 The policy session file generated via the -S option to tpm2_star‐
40 tauthsession(1).
41 • ARGUMENT: The calculated digest of all PCR values specified as a hex
43 byte stream. Eg: openssl dgst -sha256 -binary pcr.bin | xxd -p -c 32
44 References
47 The type of a context object, whether it is a handle or file name, is
48 determined according to the following logic in-order:
49 • If the argument is a file path, then the file is loaded as a restored
51 TPM transient object.
52 • If the argument is a prefix match on one of:
54 • owner: the owner hierarchy
56 • platform: the platform hierarchy
58 • endorsement: the endorsement hierarchy
60 • lockout: the lockout control persistent object
62 • If the argument argument can be loaded as a number it will be treat
64 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
65
67 Authorization for use of an object in TPM2.0 can come in 3 different
68 forms: 1. Password 2. HMAC 3. Sessions
69 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
71 fied”.
72 Passwords
74 Passwords are interpreted in the following forms below using prefix
75 identifiers.
76 Note: By default passwords are assumed to be in the string form when
78 they do not have a prefix.
79 String
81 A string password, specified by prefix “str:” or it’s absence (raw
82 string without prefix) is not interpreted, and is directly used for au‐
83 thorization.
84 Examples
86 foobar
87 str:foobar
88 Hex-string
90 A hex-string password, specified by prefix “hex:” is converted from a
91 hexidecimal form into a byte array form, thus allowing passwords with
92 non-printable and/or terminal un-friendly characters.
93 Example
95 hex:0x1122334455667788
96 File
98 A file based password, specified be prefix “file:” should be the path
99 of a file containing the password to be read by the tool or a “-” to
100 use stdin. Storing passwords in files prevents information leakage,
101 passwords passed as options can be read from the process list or common
102 shell history features.
103 Examples
105 # to use stdin and be prompted
106 file:-
107 # to use a file from a path
109 file:path/to/password/file
110 # to echo a password via stdin:
112 echo foobar | tpm2_tool -p file:-
113 # to use a bash here-string via stdin:
115 tpm2_tool -p file:- <<< foobar
117 Sessions
119 When using a policy session to authorize the use of an object, prefix
120 the option argument with the session keyword. Then indicate a path to
121 a session file that was created with tpm2_startauthsession(1). Option‐
122 ally, if the session requires an auth value to be sent with the session
123 handle (eg policy password), then append a + and a string as described
124 in the Passwords section.
125 Examples
127 To use a session context file called session.ctx.
128 session:session.ctx
130 To use a session context file called session.ctx AND send the authvalue
132 mypassword.
133 session:session.ctx+mypassword
135 To use a session context file called session.ctx AND send the HEX auth‐
137 value 0x11223344.
138 session:session.ctx+hex:11223344
140 PCR Authorizations
142 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
143 language. The PCR minilanguage is as follows:
144 <pcr-spec>=<raw-pcr-file>
145 The PCR spec is documented in in the section “PCR bank specifiers”.
147 The raw-pcr-file is an optional argument that contains the output of
149 the raw PCR contents as returned by tpm2_pcrread(1).
150 PCR bank specifiers (pcr.md)
152 Examples
154 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
155 er of:
156 pcr:sha256:0,1,2,3
158 specifying AUTH.
160
162 PCR Bank Selection lists follow the below specification:
163 <BANK>:<PCR>[,<PCR>] or <BANK>:all
165 multiple banks may be separated by `+'.
167 For example:
169 sha1:3,4+sha256:all
171 will select PCRs 3 and 4 from the SHA1 bank and PCRs 0 to 23 from the
173 SHA256 bank.
174 Note
176 PCR Selections allow for up to 5 hash to pcr selection mappings. This
177 is a limitation in design in the single call to the tpm to get the pcr
178 values. PCR.
179
181 This collection of options are common to many programs and provide in‐
182 formation that many users may expect.
183 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
185 attempts to invoke the manpager for the tool, however, on failure
186 will output a short tool summary. This is the same behavior if the
187 “man” option argument is specified, however if explicit “man” is re‐
188 quested, the tool will provide errors from man on stderr. If the
189 “no-man” option if specified, or the manpager fails, the short op‐
190 tions will be output to stdout.
191 To successfully use the manpages feature requires the manpages to be
193 installed or on MANPATH, See man(1) for more details.
194 • -v, --version: Display version information for this tool, supported
196 tctis and exit.
197 • -V, --verbose: Increase the information that the tool prints to the
199 console during its execution. When using this option the file and
200 line number are printed.
201 • -Q, --quiet: Silence normal tool output to stdout.
203 • -Z, --enable-errata: Enable the application of errata fixups. Useful
205 if an errata fixup needs to be applied to commands sent to the TPM.
206 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
207 formation many users may expect.
208
210 The TCTI or “Transmission Interface” is the communication mechanism
211 with the TPM. TCTIs can be changed for communication with TPMs across
212 different mediums.
213 To control the TCTI, the tools respect:
215 1. The command line option -T or --tcti
217 2. The environment variable: TPM2TOOLS_TCTI.
219 Note: The command line option always overrides the environment vari‐
221 able.
222 The current known TCTIs are:
224 • tabrmd - The resource manager, called tabrmd
226 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
227 abrmd as a tcti name are synonymous.
228 • mssim - Typically used for communicating to the TPM software simula‐
230 tor.
231 • device - Used when talking directly to a TPM device file.
233 • none - Do not initalize a connection with the TPM. Some tools allow
235 for off-tpm options and thus support not using a TCTI. Tools that do
236 not support it will error when attempted to be used without a TCTI
237 connection. Does not support ANY options and MUST BE presented as
238 the exact text of “none”.
239 The arguments to either the command line option or the environment
241 variable are in the form:
242 <tcti-name>:<tcti-option-config>
244 Specifying an empty string for either the <tcti-name> or <tcti-op‐
246 tion-config> results in the default being used for that portion respec‐
247 tively.
248 TCTI Defaults
250 When a TCTI is not specified, the default TCTI is searched for using
251 dlopen(3) semantics. The tools will search for tabrmd, device and
252 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
253 what TCTI will be chosen as the default by using the -v option to print
254 the version information. The “default-tcti” key-value pair will indi‐
255 cate which of the aforementioned TCTIs is the default.
256 Custom TCTIs
258 Any TCTI that implements the dynamic TCTI interface can be loaded. The
259 tools internally use dlopen(3), and the raw tcti-name value is used for
260 the lookup. Thus, this could be a path to the shared library, or a li‐
261 brary name as understood by dlopen(3) semantics.
262
264 This collection of options are used to configure the various known TCTI
265 modules available:
266 • device: For the device TCTI, the TPM character device file for use by
268 the device TCTI can be specified. The default is /dev/tpm0.
269 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
271 vice:/dev/tpm0”
272 • mssim: For the mssim TCTI, the domain name or IP address and port
274 number used by the simulator can be specified. The default are
275 127.0.0.1 and 2321.
276 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
278 TI=“mssim:host=localhost,port=2321”
279 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
281 ries of simple key value pairs separated by a `,' character. Each
282 key and value string are separated by a `=' character.
283 • TCTI abrmd supports two keys:
285 1. `bus_name' : The name of the tabrmd service on the bus (a
287 string).
288 2. `bus_type' : The type of the dbus instance (a string) limited to
290 `session' and `system'.
291 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
293 ample.FooBar:
294 \--tcti=tabrmd:bus_name=com.example.FooBar
296 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298 sion:
299 \--tcti:bus_type=session
301 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
303 ules.
304
306 Starts a trial session, builds a PCR policy and uses that policy in the
307 creation of an object. Then, it uses a policy session to unseal some
308 data stored in the object.
309 Step 1: create a policy
311 tpm2_createprimary -C e -g sha256 -G ecc -c primary.ctx
312 tpm2_pcrread -o pcr.dat "sha1:0,1,2,3"
314 tpm2_startauthsession -S session.dat
316 tpm2_policypcr -S session.dat -l "sha1:0,1,2,3" -f pcr.dat -L policy.dat
318 tpm2_flushcontext session.dat
320
322 tpm2_create -Q -u key.pub -r key.priv -C primary.ctx -L policy.dat \
323 -i- <<< "12345678"
324 tpm2_load -C primary.ctx -u key.pub -r key.priv -n unseal.key.name \
326 -c unseal.key.ctx
327 Step 3: Satisfy the policy
329 tpm2_startauthsession --policy-session -S session.dat
330 tpm2_policypcr -S session.dat -l "sha1:0,1,2,3" -f pcr.dat -L policy.dat
332 Step 4: Use the policy
334 tpm2_unseal -psession:session.dat -c unseal.key.ctx
335 12345678
336 tpm2_flushcontext session.dat
338
340 Tools can return any of the following codes:
341 • 0 - Success.
343 • 1 - General non-specific error.
345 • 2 - Options handling error.
347 • 3 - Authentication error.
349 • 4 - TCTI related error.
351 • 5 - Non supported scheme. Applicable to tpm2_testparams.
353
355 It expects a session to be already established via tpm2_startauthses‐
356 sion(1) and requires one of the following:
357 • direct device access
359 • extended session support with tpm2-abrmd.
361 Without it, most resource managers will not save session state between
363 command invocations.
364
366 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
367
369 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
370tpm2-tools tpm2_policypcr(1)