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 argument that contains  the  output  of
142       the raw PCR contents as returned by tpm2_pcrread(1).
143
144       PCR bank specifiers (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 and
313       sha384 hash
314       /tpm2_create  -C  parent.ctx  -G  ecc256:ecdaa4-sha384  -u  key.pub  -r
315       key.priv cryptographic algorithms ALGORITHM.
316

Object Attributes

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

PCR Bank Specifiers

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

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

Returns

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

BUGS

506       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
507

HELP

509       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
510
511
512
513tpm2-tools                                                 tpm2_pcrallocate(1)
Impressum