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

NAME

6       tpm2_policypcr(1) - Create a policy that includes specific PCR values.
7

SYNOPSIS

9       tpm2_policypcr [OPTIONS]
10

DESCRIPTION

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.
17

OPTIONS

19       · -L, --policy=FILE:
20
21         File to save the policy digest.
22
23       · -f, --pcr=FILE:
24
25         Optional  Path or Name of the file containing expected PCR values for
26         the specified index.  Default is to read the current PCRs per the set
27         list.
28
29       · -l, --pcr-list=PCR:
30
31         The list of PCR banks and selected PCRs' ids for each bank.
32
33       · -S, --session=FILE:
34
35         The  policy  session  file  generated via the -S option to tpm2_star‐
36         tauthsession(1).
37
38   References

Context Object Format

40       The type of a context object, whether it is a handle or file  name,  is
41       determined according to the following logic in-order:
42
43       · If the argument is a file path, then the file is loaded as a restored
44         TPM transient object.
45
46       · If the argument is a prefix match on one of:
47
48         · owner: the owner hierarchy
49
50         · platform: the platform hierarchy
51
52         · endorsement: the endorsement hierarchy
53
54         · lockout: the lockout control persistent object
55
56       · If the argument argument can be loaded as a number it will  be  treat
57         as a handle, e.g.  0x81010013 and used directly.OBJECT.
58

Authorization Formatting

60       Authorization  for  use  of an object in TPM2.0 can come in 3 different
61       forms: 1.  Password 2.  HMAC 3.  Sessions
62
63       NOTE: "Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
64       fied".
65
66   Passwords
67       Passwords  are  interpreted  in  the following forms below using prefix
68       identifiers.
69
70       Note: By default passwords are assumed to be in the  string  form  when
71       they do not have a prefix.
72
73   String
74       A  string  password,  specified  by  prefix "str:" or it's absence (raw
75       string without prefix) is not interpreted, and is directly used for au‐
76       thorization.
77
78   Examples
79              foobar
80              str:foobar
81
82   Hex-string
83       A  hex-string  password, specified by prefix "hex:" is converted from a
84       hexidecimal form into a byte array form, thus allowing  passwords  with
85       non-printable and/or terminal un-friendly characters.
86
87   Example
88              hex:0x1122334455667788
89
90   File
91       A  file  based password, specified be prefix "file:" should be the path
92       of a file containing the password to be read by the tool or  a  "-"  to
93       use  stdin.   Storing  passwords in files prevents information leakage,
94       passwords passed as options can be read from the process list or common
95       shell history features.
96
97   Examples
98              # to use stdin and be prompted
99              file:-
100
101              # to use a file from a path
102              file:path/to/password/file
103
104              # to echo a password via stdin:
105              echo foobar | tpm2_tool -p file:-
106
107              # to use a bash here-string via stdin:
108
109              tpm2_tool -p file:- <<< foobar
110
111   Sessions
112       When  using  a policy session to authorize the use of an object, prefix
113       the option argument with the session keyword.  Then indicate a path  to
114       a session file that was created with tpm2_startauthsession(1).  Option‐
115       ally, if the session requires an auth value to be sent with the session
116       handle  (eg policy password), then append a + and a string as described
117       in the Passwords section.
118
119   Examples
120       To use a session context file called session.ctx.
121
122              session:session.ctx
123
124       To use a session context file called session.ctx AND send the authvalue
125       mypassword.
126
127              session:session.ctx+mypassword
128
129       To use a session context file called session.ctx AND send the HEX auth‐
130       value 0x11223344.
131
132              session:session.ctx+hex:11223344
133
134   PCR Authorizations
135       You can satisfy a PCR policy using the "pcr:" prefix and the PCR  mini‐
136       language.       The     PCR     minilanguage     is     as     follows:
137       <pcr-spec>=<raw-pcr-file>
138
139       The PCR spec is documented in in the section "PCR bank specifiers".
140
141       The raw-pcr-file is an optional the output of the raw PCR  contents  as
142       returned by tpm2_pcrread(1).
143
144       PCR bank specifiers (common/pcr.md)
145
146   Examples
147       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
148       er of:
149
150              pcr:sha256:0,1,2,3
151
152       specifying AUTH.
153

PCR Bank Specifiers

155       PCR Bank Selection lists follow the below specification:
156
157              <BANK>:<PCR>[,<PCR>] or <BANK>:all
158
159       multiple banks may be separated by '+'.
160
161       For example:
162
163              sha1:3,4+sha256:all
164
165       will select PCRs 3 and 4 from the SHA1 bank and PCRs 0 to 23  from  the
166       SHA256 bank.
167
168   Note
169       PCR  Selections allow for up to 5 hash to pcr selection mappings.  This
170       is a limitation in design in the single call to the tpm to get the  pcr
171       values.  PCR.
172

COMMON OPTIONS

174       This  collection of options are common to many programs and provide in‐
175       formation that many users may expect.
176
177       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
178         attempts  to  invoke  the  manpager for the tool, however, on failure
179         will output a short tool summary.  This is the same behavior  if  the
180         "man"  option argument is specified, however if explicit "man" is re‐
181         quested, the tool will provide errors from man  on  stderr.   If  the
182         "no-man"  option  if  specified, or the manpager fails, the short op‐
183         tions will be output to stdout.
184
185         To successfully use the manpages feature requires the manpages to  be
186         installed or on MANPATH, See man(1) for more details.
187
188       · -v,  --version:  Display version information for this tool, supported
189         tctis and exit.
190
191       · -V, --verbose: Increase the information that the tool prints  to  the
192         console  during  its  execution.  When using this option the file and
193         line number are printed.
194
195       · -Q, --quiet: Silence normal tool output to stdout.
196
197       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
198         if  an  errata fixup needs to be applied to commands sent to the TPM.
199         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
200         formation many users may expect.
201

TCTI Configuration

203       The  TCTI  or  "Transmission  Interface" is the communication mechanism
204       with the TPM.  TCTIs can be changed for communication with TPMs  across
205       different mediums.
206
207       To control the TCTI, the tools respect:
208
209       1. The command line option -T or --tcti
210
211       2. The environment variable: TPM2TOOLS_TCTI.
212
213       Note:  The  command  line option always overrides the environment vari‐
214       able.
215
216       The current known TCTIs are:
217
218       · tabrmd     -     The     resource     manager,     called      tabrmd
219         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
220         abrmd as a tcti name are synonymous.
221
222       · mssim - Typically used for communicating to the TPM software  simula‐
223         tor.
224
225       · device - Used when talking directly to a TPM device file.
226
227       · none  - Do not initalize a connection with the TPM.  Some tools allow
228         for off-tpm options and thus support not using a TCTI.  Tools that do
229         not  support  it  will error when attempted to be used without a TCTI
230         connection.  Does not support ANY options and MUST  BE  presented  as
231         the exact text of "none".
232
233       The  arguments  to  either  the  command line option or the environment
234       variable are in the form:
235
236       <tcti-name>:<tcti-option-config>
237
238       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
239       tion-config> results in the default being used for that portion respec‐
240       tively.
241
242   TCTI Defaults
243       When a TCTI is not specified, the default TCTI is  searched  for  using
244       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
245       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
246       what TCTI will be chosen as the default by using the -v option to print
247       the version information.  The "default-tcti" key-value pair will  indi‐
248       cate which of the aforementioned TCTIs is the default.
249
250   Custom TCTIs
251       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
252       tools internally use dlopen(3), and the raw tcti-name value is used for
253       the lookup.  Thus, this could be a path to the shared library, or a li‐
254       brary name as understood by dlopen(3) semantics.
255

TCTI OPTIONS

257       This collection of options are used to configure the various known TCTI
258       modules available:
259
260       · device: For the device TCTI, the TPM character device file for use by
261         the device TCTI can be specified.  The default is /dev/tpm0.
262
263         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
264         vice:/dev/tpm0"
265
266       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
267         number used by the simulator  can  be  specified.   The  default  are
268         127.0.0.1 and 2321.
269
270         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
271         TI="mssim:host=localhost,port=2321"
272
273       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
274         ries  of  simple  key value pairs separated by a ',' character.  Each
275         key and value string are separated by a '=' character.
276
277         · TCTI abrmd supports two keys:
278
279           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
280              string).
281
282           2. 'bus_type' : The type of the dbus instance (a string) limited to
283              'session' and 'system'.
284
285         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
286         ample.FooBar:
287
288         \--tcti=tabrmd:bus_name=com.example.FooBar
289
290         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
291         sion:
292
293         \--tcti:bus_type=session
294
295         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
296         ules.
297

EXAMPLES

299       Starts a trial session, builds a PCR policy and uses that policy in the
300       creation of an object.  Then, it uses a policy session to  unseal  some
301       data stored in the object.
302
303   Step 1: create a policy
304              tpm2_createprimary -C e -g sha256 -G ecc -c primary.ctx
305
306              tpm2_pcrread -o pcr.dat "sha1:0,1,2,3"
307
308              tpm2_startauthsession -S session.dat
309
310              tpm2_policypcr -S session.dat -l "sha1:0,1,2,3" -f pcr.dat -L policy.dat
311
312              tpm2_flushcontext session.dat
313

Step 2: create an object using that policy

315              tpm2_create -Q -u key.pub -r key.priv -C primary.ctx -L policy.dat \
316              -i- <<< "12345678"
317
318              tpm2_load -C primary.ctx -u key.pub -r key.priv -n unseal.key.name \
319              -c unseal.key.ctx
320
321   Step 3: Satisfy the policy
322              tpm2_startauthsession --policy-session -S session.dat
323
324              tpm2_policypcr -S session.dat -l "sha1:0,1,2,3" -f pcr.dat -L policy.dat
325
326   Step 4: Use the policy
327              tpm2_unseal -psession:session.dat -c unseal.key.ctx
328              12345678
329
330              tpm2_flushcontext session.dat
331

Returns

333       Tools can return any of the following codes:
334
335       · 0 - Success.
336
337       · 1 - General non-specific error.
338
339       · 2 - Options handling error.
340
341       · 3 - Authentication error.
342
343       · 4 - TCTI related error.
344
345       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
346

Limitations

348       It  expects  a session to be already established via tpm2_startauthses‐
349       sion(1) and requires one of the following:
350
351       · direct device access
352
353       · extended session support with tpm2-abrmd.
354
355       Without it, most resource managers will not save session state  between
356       command invocations.
357

BUGS

359       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
360

HELP

362       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
363
364
365
366tpm2-tools                                                   tpm2_policypcr(1)