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

NAME

6       tpm2_pcrallocate(1) - Configure PCRs and bank algorithms.
7

SYNOPSIS

9       tpm2_pcrallocate [OPTIONS] [*ARGUMENT]
10

DESCRIPTION

12       tpm2_pcrallocate(1)  -  Allow  the user to specify a PCR allocation for
13       the TPM.  An allocation is the enabling or disabling of PCRs  and  it's
14       banks.   A  PCR  can have multiple banks, where each bank is associated
15       with a specific hashing algorithm.  Allocation is specified in the  ar‐
16       gument.
17
18       If  no allocation is given, then SHA1 and SHA256 banks with PCRs 0 - 23
19       are allocated.
20
21       Allocation is a list of banks and selected  pcrs.   The  values  should
22       follow  the pcr bank specifiers standards, see section "PCR Bank Speci‐
23       fiers".
24
25       The new allocations become effective after the next reboot.
26
27       Note: This command requires platform authorization.
28

OPTIONS

30-P, --auth=AUTH:
31
32         Optional authorization value.  Authorization values should follow the
33         "authorization formatting standards", see section "Authorization For‐
34         matting".
35
36ARGUMENT the command line argument specifies the PCR allocation.
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

Algorithm Specifiers

155       Options that take algorithms support "nice-names".
156
157       There are two major algorithm specification string classes, simple  and
158       complex.  Only certain algorithms will be accepted by the TPM, based on
159       usage and conditions.
160
161   Simple specifiers
162       These are strings with no additional specification data.  When creating
163       objects,  non-specified  portions of an object are assumed to defaults.
164       You can find the list of known "Simple Specifiers Below".
165
166   Asymmetric
167       • rsa
168
169       • ecc
170
171   Symmetric
172       • aes
173
174       • camellia
175
176   Hashing Algorithms
177       • sha1
178
179       • sha256
180
181       • sha384
182
183       • sha512
184
185       • sm3_256
186
187       • sha3_256
188
189       • sha3_384
190
191       • sha3_512
192
193   Keyed Hash
194       • hmac
195
196       • xor
197
198   Signing Schemes
199       • rsassa
200
201       • rsapss
202
203       • ecdsa
204
205       • ecdaa
206
207       • ecschnorr
208
209   Asymmetric Encryption Schemes
210       • oaep
211
212       • rsaes
213
214       • ecdh
215
216   Modes
217       • ctr
218
219       • ofb
220
221       • cbc
222
223       • cfb
224
225       • ecb
226
227   Misc
228       • null
229
230   Complex Specifiers
231       Objects, when specified for creation by the TPM,  have  numerous  algo‐
232       rithms  to  populate  in the public data.  Things like type, scheme and
233       asymmetric details, key size, etc.  Below is  the  general  format  for
234       specifying this data: <type>:<scheme>:<symmetric-details>
235
236   Type Specifiers
237       This  portion  of the complex algorithm specifier is required.  The re‐
238       maining scheme and symmetric details will default  based  on  the  type
239       specified and the type of the object being created.
240
241       • aes - Default AES: aes128
242
243       • aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
244         If mode is not specified, defaults to null.
245
246       • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
247
248       • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
249
250       • ecc - Elliptical Curve, defaults to ecc256.
251
252       • ecc192 - 192 bit ECC
253
254       • ecc224 - 224 bit ECC
255
256       • ecc256 - 256 bit ECC
257
258       • ecc384 - 384 bit ECC
259
260       • ecc521 - 521 bit ECC
261
262       • rsa - Default RSA: rsa2048
263
264       • rsa1024 - RSA with 1024 bit keysize.
265
266       • rsa2048 - RSA with 2048 bit keysize.
267
268       • rsa4096 - RSA with 4096 bit keysize.
269
270   Scheme Specifiers
271       Next, is an optional field, it can be skipped.
272
273       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
274       Most signing schemes take a hash algorithm directly following the sign‐
275       ing scheme.  If the hash algorithm is missing, it defaults  to  sha256.
276       Some take no arguments, and some take multiple arguments.
277
278   Hash Optional Scheme Specifiers
279       These  scheme  specifiers are followed by a dash and a valid hash algo‐
280       rithm, For example: oaep-sha256.
281
282       • oaep
283
284       • ecdh
285
286       • rsassa
287
288       • rsapss
289
290       • ecdsa
291
292       • ecschnorr
293
294   Multiple Option Scheme Specifiers
295       This scheme specifier is followed by a count  (max  size  UINT16)  then
296       followed by a dash(-) and a valid hash algorithm.  * ecdaa For example,
297       ecdaa4-sha256.  If no count is specified, it defaults to 4.
298
299   No Option Scheme Specifiers
300       This scheme specifier takes NO arguments.  * rsaes
301
302   Symmetric Details Specifiers
303       This field is optional, and defaults based on the type of object  being
304       created  and it's attributes.  Generally, any valid Symmetric specifier
305       from the Type Specifiers list should work.  If not specified, an  asym‐
306       metric objects symmetric details defaults to aes128cfb.
307
308   Examples
309   Create an rsa2048 key with an rsaes asymmetric encryption scheme
310       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
311
312   Create an ecc256 key with an ecdaa signing scheme with a count of 4
313       and sha384 hash
314
315       /tpm2_create -C parent.ctx -G ecc256:ec‐
316       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
317

Object Attributes

319       Object Attributes are used to control various properties of created ob‐
320       jects.   When  specified  as an option, either the raw bitfield mask or
321       "nice-names" may be used.  The values can be found in Table 31  Part  2
322       of the TPM2.0 specification, which can be found here:
323
324       <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
325       Rev-2.0-Part-2-Structures-01.38.pdf>
326
327       Nice names are calculated by taking the name field of table 31 and  re‐
328       moving  the  prefix TPMA_OBJECT_ and lowercasing the result.  Thus, TP‐
329       MA_OBJECT_FIXEDTPM becomes fixedtpm.  Nice names can  be  joined  using
330       the bitwise or "|" symbol.
331
332       For instance, to set The fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
333       and TPMA_OBJECT_SIGN_ENCRYPT, the argument would be:
334
335       fixedtpm|noda|sign specifying the object attributes ATTRIBUTES.
336

PCR Bank Specifiers

338       PCR Bank Selection lists follow the below specification:
339
340              <BANK>:<PCR>[,<PCR>] or <BANK>:all
341
342       multiple banks may be separated by '+'.
343
344       For example:
345
346              sha1:3,4+sha256:all
347
348       will select PCRs 3 and 4 from the SHA1 bank and PCRs 0 to 23  from  the
349       SHA256 bank.
350
351   Note
352       PCR  Selections allow for up to 5 hash to pcr selection mappings.  This
353       is a limitation in design in the single call to the tpm to get the  pcr
354       values.
355

COMMON OPTIONS

357       This  collection of options are common to many programs and provide in‐
358       formation that many users may expect.
359
360-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
361         attempts  to  invoke  the  manpager for the tool, however, on failure
362         will output a short tool summary.  This is the same behavior  if  the
363         "man"  option argument is specified, however if explicit "man" is re‐
364         quested, the tool will provide errors from man  on  stderr.   If  the
365         "no-man"  option  if  specified, or the manpager fails, the short op‐
366         tions will be output to stdout.
367
368         To successfully use the manpages feature requires the manpages to  be
369         installed or on MANPATH, See man(1) for more details.
370
371-v,  --version:  Display version information for this tool, supported
372         tctis and exit.
373
374-V, --verbose: Increase the information that the tool prints  to  the
375         console  during  its  execution.  When using this option the file and
376         line number are printed.
377
378-Q, --quiet: Silence normal tool output to stdout.
379
380-Z, --enable-errata: Enable the application of errata fixups.  Useful
381         if  an  errata fixup needs to be applied to commands sent to the TPM.
382         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
383         formation many users may expect.
384

TCTI Configuration

386       The  TCTI  or  "Transmission  Interface" is the communication mechanism
387       with the TPM.  TCTIs can be changed for communication with TPMs  across
388       different mediums.
389
390       To control the TCTI, the tools respect:
391
392       1. The command line option -T or --tcti
393
394       2. The environment variable: TPM2TOOLS_TCTI.
395
396       Note:  The  command  line option always overrides the environment vari‐
397       able.
398
399       The current known TCTIs are:
400
401       • tabrmd     -     The     resource     manager,     called      tabrmd
402         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
403         abrmd as a tcti name are synonymous.
404
405       • mssim - Typically used for communicating to the TPM software  simula‐
406         tor.
407
408       • device - Used when talking directly to a TPM device file.
409
410       • none  - Do not initalize a connection with the TPM.  Some tools allow
411         for off-tpm options and thus support not using a TCTI.  Tools that do
412         not  support  it  will error when attempted to be used without a TCTI
413         connection.  Does not support ANY options and MUST  BE  presented  as
414         the exact text of "none".
415
416       The  arguments  to  either  the  command line option or the environment
417       variable are in the form:
418
419       <tcti-name>:<tcti-option-config>
420
421       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
422       tion-config> results in the default being used for that portion respec‐
423       tively.
424
425   TCTI Defaults
426       When a TCTI is not specified, the default TCTI is  searched  for  using
427       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
428       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
429       what TCTI will be chosen as the default by using the -v option to print
430       the version information.  The "default-tcti" key-value pair will  indi‐
431       cate which of the aforementioned TCTIs is the default.
432
433   Custom TCTIs
434       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
435       tools internally use dlopen(3), and the raw tcti-name value is used for
436       the lookup.  Thus, this could be a path to the shared library, or a li‐
437       brary name as understood by dlopen(3) semantics.
438

TCTI OPTIONS

440       This collection of options are used to configure the various known TCTI
441       modules available:
442
443device: For the device TCTI, the TPM character device file for use by
444         the device TCTI can be specified.  The default is /dev/tpm0.
445
446         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
447         vice:/dev/tpm0"
448
449        mssim:  For  the  mssim  TCTI, the domain name or IP address and port
450         number used by the simulator  can  be  specified.   The  default  are
451         127.0.0.1 and 2321.
452
453         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
454         TI="mssim:host=localhost,port=2321"
455
456        abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
457         ries  of  simple  key value pairs separated by a ',' character.  Each
458         key and value string are separated by a '=' character.
459
460         • TCTI abrmd supports two keys:
461
462           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
463              string).
464
465           2. 'bus_type' : The type of the dbus instance (a string) limited to
466              'session' and 'system'.
467
468         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
469         ample.FooBar:
470
471         \--tcti=tabrmd:bus_name=com.example.FooBar
472
473         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
474         sion:
475
476         \--tcti:bus_type=session
477
478         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
479         ules.
480

EXAMPLES

482   To allocate the two default banks (SHA1 and SHA256)
483              tpm2_pcrallocate
484
485   To make a custom allocation with a platform authorization
486              tpm2_pcrallocate -P abc sha1:7,8,9,10,16,17,18,19+sha256:all
487
488   To completly switch from SHA1 bank to SHA256 with a platform
489       authorization
490
491              tpm2_pcrallocate -P abc sha1:none+sha256:all
492

Returns

494       Tools can return any of the following codes:
495
496       • 0 - Success.
497
498       • 1 - General non-specific error.
499
500       • 2 - Options handling error.
501
502       • 3 - Authentication error.
503
504       • 4 - TCTI related error.
505
506       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
507

BUGS

509       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
510

HELP

512       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
513
514
515
516tpm2-tools                                                 tpm2_pcrallocate(1)
Impressum