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

OPTIONS

23-L, --policy=FILE:
24
25         File to save the policy digest.
26
27-f, --pcr=FILE:
28
29         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
33-l, --pcr-list=PCR:
34
35         The list of PCR banks and selected PCRs’ ids for each bank.
36
37-S, --session=FILE:
38
39         The  policy  session  file  generated via the -S option to tpm2_star‐
40         tauthsession(1).
41
42ARGUMENT: 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
45   References

Context Object Format

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
50       • If the argument is a file path, then the file is loaded as a restored
51         TPM transient object.
52
53       • If the argument is a prefix match on one of:
54
55         • owner: the owner hierarchy
56
57         • platform: the platform hierarchy
58
59         • endorsement: the endorsement hierarchy
60
61         • lockout: the lockout control persistent object
62
63       • 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

Authorization Formatting

67       Authorization for use of an object in TPM2.0 can come  in  3  different
68       forms: 1.  Password 2.  HMAC 3.  Sessions
69
70       NOTE:  “Authorizations  default  to  the EMPTY PASSWORD when not speci‐
71       fied”.
72
73   Passwords
74       Passwords are interpreted in the following  forms  below  using  prefix
75       identifiers.
76
77       Note:  By  default  passwords are assumed to be in the string form when
78       they do not have a prefix.
79
80   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
85   Examples
86              foobar
87              str:foobar
88
89   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
94   Example
95              hex:1122334455667788
96
97   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
104   Examples
105              # to use stdin and be prompted
106              file:-
107
108              # to use a file from a path
109              file:path/to/password/file
110
111              # to echo a password via stdin:
112              echo foobar | tpm2_tool -p file:-
113
114              # to use a bash here-string via stdin:
115
116              tpm2_tool -p file:- <<< foobar
117
118   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
126   Examples
127       To use a session context file called session.ctx.
128
129              session:session.ctx
130
131       To use a session context file called session.ctx AND send the authvalue
132       mypassword.
133
134              session:session.ctx+mypassword
135
136       To use a session context file called session.ctx AND send the HEX auth‐
137       value 0x11223344.
138
139              session:session.ctx+hex:11223344
140
141   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
146       The PCR spec is documented in in the section “PCR bank specifiers”.
147
148       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
151       PCR bank specifiers (pcr.md)
152
153   Examples
154       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
155       er of:
156
157              pcr:sha256:0,1,2,3
158
159       specifying AUTH.
160

PCR Bank Specifiers

162       PCR Bank Selection lists follow the below specification:
163
164              <BANK>:<PCR>[,<PCR>] or <BANK>:all
165
166       multiple banks may be separated by `+'.
167
168       For example:
169
170              sha1:3,4+sha256:all
171
172       will  select  PCRs 3 and 4 from the SHA1 bank and PCRs 0 to 23 from the
173       SHA256 bank.
174
175   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

COMMON OPTIONS

181       This collection of options are common to many programs and provide  in‐
182       formation that many users may expect.
183
184-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
192         To  successfully use the manpages feature requires the manpages to be
193         installed or on MANPATH, See man(1) for more details.
194
195-v, --version: Display version information for this  tool,  supported
196         tctis and exit.
197
198-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
202-Q, --quiet: Silence normal tool output to stdout.
203
204-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

TCTI Configuration

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
214       To control the TCTI, the tools respect:
215
216       1. The command line option -T or --tcti
217
218       2. The environment variable: TPM2TOOLS_TCTI.
219
220       Note: The command line option always overrides  the  environment  vari‐
221       able.
222
223       The current known TCTIs are:
224
225       • 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
229       • mssim  - Typically used for communicating to the TPM software simula‐
230         tor.
231
232       • device - Used when talking directly to a TPM device file.
233
234       • 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
240       The arguments to either the command  line  option  or  the  environment
241       variable are in the form:
242
243       <tcti-name>:<tcti-option-config>
244
245       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
249   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
257   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

TCTI OPTIONS

264       This collection of options are used to configure the various known TCTI
265       modules available:
266
267device: 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
270         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
271         vice:/dev/tpm0”
272
273mssim: 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
277         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
278         TI=“mssim:host=localhost,port=2321”
279
280abrmd:  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
284         • TCTI abrmd supports two keys:
285
286           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
287              string).
288
289           2. `bus_type' : The type of the dbus instance (a string) limited to
290              `session' and `system'.
291
292         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
293         ample.FooBar:
294
295                \--tcti=tabrmd:bus_name=com.example.FooBar
296
297         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298         sion:
299
300                \--tcti:bus_type=session
301
302         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
303         ules.
304

EXAMPLES

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
310   Step 1: create a policy
311              tpm2_createprimary -C e -g sha256 -G ecc -c primary.ctx
312
313              tpm2_pcrread -o pcr.dat "sha1:0,1,2,3"
314
315              tpm2_startauthsession -S session.dat
316
317              tpm2_policypcr -S session.dat -l "sha1:0,1,2,3" -f pcr.dat -L policy.dat
318
319              tpm2_flushcontext session.dat
320

Step 2: create an object using that policy

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

Returns

340       Tools can return any of the following codes:
341
342       • 0 - Success.
343
344       • 1 - General non-specific error.
345
346       • 2 - Options handling error.
347
348       • 3 - Authentication error.
349
350       • 4 - TCTI related error.
351
352       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
353

Limitations

355       It expects a session to be already established  via  tpm2_startauthses‐
356       sion(1) and requires one of the following:
357
358       • direct device access
359
360       • extended session support with tpm2-abrmd.
361
362       Without  it, most resource managers will not save session state between
363       command invocations.
364

BUGS

366       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
367

HELP

369       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
370       fo/tpm2)
371
372
373
374tpm2-tools                                                   tpm2_policypcr(1)
Impressum