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 the output of the raw PCR  contents  as
150       returned by tpm2_pcrread(1).
151
152       PCR bank specifiers (common/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       folloed  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
321       and sha384 hash
322
323       /tpm2_create -C parent.ctx -G ecc256:ec‐
324       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
325

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

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

Returns

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

BUGS

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

HELP

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