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

NAME

6       tpm2_setprimarypolicy(1)  - Sets the authorization policy for the lock‐
7       out (lockoutPolicy), the platform hierarchy (platformPolicy), the stor‐
8       age  hierarchy  (ownerPolicy),  and the endorsement hierarchy (endorse‐
9       mentPolicy).
10

SYNOPSIS

12       tpm2_setprimarypolicy [OPTIONS]
13

DESCRIPTION

15       tpm2_setprimarypolicy(1) - Sets the authorization policy for the  lock‐
16       out (lockoutPolicy), the platform hierarchy (platformPolicy), the stor‐
17       age hierarchy (ownerPolicy), and the  endorsement  hierarchy  (endorse‐
18       mentPolicy).
19

OPTIONS

21       These options control creating the policy authorization session:
22
23-C, --hierarchy=OBJECT:
24
25         Specifies  the  hierarchy  whose authorization policy is to be setup.
26         It can be specified as o|p|e|l
27
28-P, --auth=AUTH:
29
30         Specifies the authorization value for the hierarchy.
31
32-L, --policy=FILE:
33
34         The file path of the authorization policy data.
35
36-g, --hash-algorithm=ALGORITHM:
37
38         The hash algorithm used in computation of the policy digest.
39
40--cphash=FILE
41
42         File path to record the hash of the command parameters.  This is com‐
43         monly termed as cpHash.  NOTE: When this option is selected, The tool
44         will not actually execute the command, it simply returns a cpHash.
45
46   References

Context Object Format

48       The type of a context object, whether it is a handle or file  name,  is
49       determined according to the following logic in-order:
50
51       • If the argument is a file path, then the file is loaded as a restored
52         TPM transient object.
53
54       • If the argument is a prefix match on one of:
55
56         • owner: the owner hierarchy
57
58         • platform: the platform hierarchy
59
60         • endorsement: the endorsement hierarchy
61
62         • lockout: the lockout control persistent object
63
64       • If the argument argument can be loaded as a number it will  be  treat
65         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
66

Authorization Formatting

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

Algorithm Specifiers

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

COMMON OPTIONS

326       This  collection of options are common to many programs and provide in‐
327       formation that many users may expect.
328
329-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
330         attempts  to  invoke  the  manpager for the tool, however, on failure
331         will output a short tool summary.  This is the same behavior  if  the
332         “man”  option argument is specified, however if explicit “man” is re‐
333         quested, the tool will provide errors from man  on  stderr.   If  the
334         “no-man”  option  if  specified, or the manpager fails, the short op‐
335         tions will be output to stdout.
336
337         To successfully use the manpages feature requires the manpages to  be
338         installed or on MANPATH, See man(1) for more details.
339
340-v,  --version:  Display version information for this tool, supported
341         tctis and exit.
342
343-V, --verbose: Increase the information that the tool prints  to  the
344         console  during  its  execution.  When using this option the file and
345         line number are printed.
346
347-Q, --quiet: Silence normal tool output to stdout.
348
349-Z, --enable-errata: Enable the application of errata fixups.  Useful
350         if  an  errata fixup needs to be applied to commands sent to the TPM.
351         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
352         formation many users may expect.
353

TCTI Configuration

355       The  TCTI  or  “Transmission  Interface” is the communication mechanism
356       with the TPM.  TCTIs can be changed for communication with TPMs  across
357       different mediums.
358
359       To control the TCTI, the tools respect:
360
361       1. The command line option -T or --tcti
362
363       2. The environment variable: TPM2TOOLS_TCTI.
364
365       Note:  The  command  line option always overrides the environment vari‐
366       able.
367
368       The current known TCTIs are:
369
370       • tabrmd     -     The     resource     manager,     called      tabrmd
371         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
372         abrmd as a tcti name are synonymous.
373
374       • mssim - Typically used for communicating to the TPM software  simula‐
375         tor.
376
377       • device - Used when talking directly to a TPM device file.
378
379       • none  - Do not initalize a connection with the TPM.  Some tools allow
380         for off-tpm options and thus support not using a TCTI.  Tools that do
381         not  support  it  will error when attempted to be used without a TCTI
382         connection.  Does not support ANY options and MUST  BE  presented  as
383         the exact text of “none”.
384
385       The  arguments  to  either  the  command line option or the environment
386       variable are in the form:
387
388       <tcti-name>:<tcti-option-config>
389
390       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
391       tion-config> results in the default being used for that portion respec‐
392       tively.
393
394   TCTI Defaults
395       When a TCTI is not specified, the default TCTI is  searched  for  using
396       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
397       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
398       what TCTI will be chosen as the default by using the -v option to print
399       the version information.  The “default-tcti” key-value pair will  indi‐
400       cate which of the aforementioned TCTIs is the default.
401
402   Custom TCTIs
403       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
404       tools internally use dlopen(3), and the raw tcti-name value is used for
405       the lookup.  Thus, this could be a path to the shared library, or a li‐
406       brary name as understood by dlopen(3) semantics.
407

TCTI OPTIONS

409       This collection of options are used to configure the various known TCTI
410       modules available:
411
412device: For the device TCTI, the TPM character device file for use by
413         the device TCTI can be specified.  The default is /dev/tpm0.
414
415         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
416         vice:/dev/tpm0”
417
418mssim:  For  the  mssim  TCTI, the domain name or IP address and port
419         number used by the simulator  can  be  specified.   The  default  are
420         127.0.0.1 and 2321.
421
422         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
423         TI=“mssim:host=localhost,port=2321”
424
425abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
426         ries  of  simple  key value pairs separated by a `,' character.  Each
427         key and value string are separated by a `=' character.
428
429         • TCTI abrmd supports two keys:
430
431           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
432              string).
433
434           2. `bus_type' : The type of the dbus instance (a string) limited to
435              `session' and `system'.
436
437         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
438         ample.FooBar:
439
440                \--tcti=tabrmd:bus_name=com.example.FooBar
441
442         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
443         sion:
444
445                \--tcti:bus_type=session
446
447         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
448         ules.
449

EXAMPLES

451   Set a blank authorization policy for endorsement hierarchy
452              tpm2_setprimarypolicy -C e
453

Returns

455       Tools can return any of the following codes:
456
457       • 0 - Success.
458
459       • 1 - General non-specific error.
460
461       • 2 - Options handling error.
462
463       • 3 - Authentication error.
464
465       • 4 - TCTI related error.
466
467       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
468

BUGS

470       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
471

HELP

473       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
474
475
476
477tpm2-tools                                            tpm2_setprimarypolicy(1)
Impressum