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

NAME

6       tpm2_policysecret(1)  -  Couples the authorization of an object to that
7       of an existing object.
8

SYNOPSIS

10       tpm2_policysecret [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_policysecret(1) - Couples the authorization of an object  to  that
14       of  an  existing  object without requiring exposing the existing secret
15       until time of object use.
16

OPTIONS

18-c, --object-context=OBJECT:
19
20         A context object specifier of  a  transient/permanent/persistent  ob‐
21         ject.   Either  a file path of a object context blob or a loaded/per‐
22         sistent/permanent handle id.  See section  “Context  Object  Format”.
23         As an argument, it takes the auth value of the associated TPM object,
24         a single dash - can be used to read the auth value from  stdin.   The
25         argument  follows  the “authorization formatting standards”, see sec‐
26         tion “Authorization Formatting”.
27
28-S, --session=FILE:
29
30         The policy session file generated via the  -S  option  to  tpm2_star‐
31         tauthsession(1).
32
33-L, --policy=FILE:
34
35         File to save the policy digest.
36
37-t, --expiration=NATURAL_NUMBER:
38
39         Set the expiration time of the policy in seconds.  In absence of non‐
40         ceTPM the expiration time is the policy timeout value.  If expiration
41         value  is  0 then the policy does not have a time limit on the autho‐
42         rization.
43
44--ticket=FILE:
45
46         The ticket file to record the authorization ticket structure.
47
48--timeout=FILE:
49
50         The file path to record the timeout structure returned.
51
52-x, --nonce-tpm:
53
54         Enable the comparison of the current session’s nonceTPM to ensure the
55         validity  of  the policy authorization is limited to the current ses‐
56         sion.
57
58-q, --qualification=FILE_OR_HEX_STR:
59
60         Optional, the policy qualifier data that the signer can choose to in‐
61         clude in the signature.  Can be either a hex string or path.
62
63--cphash=FILE
64
65         File path to record the hash of the command parameters.  This is com‐
66         monly termed as cpHash.  NOTE: When this option is selected, The tool
67         will  not actually execute the command, it simply returns a cpHash to
68         be used in an audit or a policycphash.
69
70ARGUMENT the command line argument specifies the AUTH to be  set  for
71         the object specified with -c.
72
73   References

Context Object Format

75       The  type  of a context object, whether it is a handle or file name, is
76       determined according to the following logic in-order:
77
78       • If the argument is a file path, then the file is loaded as a restored
79         TPM transient object.
80
81       • If the argument is a prefix match on one of:
82
83         • owner: the owner hierarchy
84
85         • platform: the platform hierarchy
86
87         • endorsement: the endorsement hierarchy
88
89         • lockout: the lockout control persistent object
90
91       • If  the  argument argument can be loaded as a number it will be treat
92         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
93

Authorization Formatting

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

COMMON OPTIONS

190       This  collection of options are common to many programs and provide in‐
191       formation that many users may expect.
192
193-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
194         attempts  to  invoke  the  manpager for the tool, however, on failure
195         will output a short tool summary.  This is the same behavior  if  the
196         “man”  option argument is specified, however if explicit “man” is re‐
197         quested, the tool will provide errors from man  on  stderr.   If  the
198         “no-man”  option  if  specified, or the manpager fails, the short op‐
199         tions will be output to stdout.
200
201         To successfully use the manpages feature requires the manpages to  be
202         installed or on MANPATH, See man(1) for more details.
203
204-v,  --version:  Display version information for this tool, supported
205         tctis and exit.
206
207-V, --verbose: Increase the information that the tool prints  to  the
208         console  during  its  execution.  When using this option the file and
209         line number are printed.
210
211-Q, --quiet: Silence normal tool output to stdout.
212
213-Z, --enable-errata: Enable the application of errata fixups.  Useful
214         if  an  errata fixup needs to be applied to commands sent to the TPM.
215         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
216         formation many users may expect.
217

TCTI Configuration

219       The  TCTI  or  “Transmission  Interface” is the communication mechanism
220       with the TPM.  TCTIs can be changed for communication with TPMs  across
221       different mediums.
222
223       To control the TCTI, the tools respect:
224
225       1. The command line option -T or --tcti
226
227       2. The environment variable: TPM2TOOLS_TCTI.
228
229       Note:  The  command  line option always overrides the environment vari‐
230       able.
231
232       The current known TCTIs are:
233
234       • tabrmd     -     The     resource     manager,     called      tabrmd
235         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
236         abrmd as a tcti name are synonymous.
237
238       • mssim - Typically used for communicating to the TPM software  simula‐
239         tor.
240
241       • device - Used when talking directly to a TPM device file.
242
243       • none  - Do not initalize a connection with the TPM.  Some tools allow
244         for off-tpm options and thus support not using a TCTI.  Tools that do
245         not  support  it  will error when attempted to be used without a TCTI
246         connection.  Does not support ANY options and MUST  BE  presented  as
247         the exact text of “none”.
248
249       The  arguments  to  either  the  command line option or the environment
250       variable are in the form:
251
252       <tcti-name>:<tcti-option-config>
253
254       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
255       tion-config> results in the default being used for that portion respec‐
256       tively.
257
258   TCTI Defaults
259       When a TCTI is not specified, the default TCTI is  searched  for  using
260       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
261       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
262       what TCTI will be chosen as the default by using the -v option to print
263       the version information.  The “default-tcti” key-value pair will  indi‐
264       cate which of the aforementioned TCTIs is the default.
265
266   Custom TCTIs
267       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
268       tools internally use dlopen(3), and the raw tcti-name value is used for
269       the lookup.  Thus, this could be a path to the shared library, or a li‐
270       brary name as understood by dlopen(3) semantics.
271

TCTI OPTIONS

273       This collection of options are used to configure the various known TCTI
274       modules available:
275
276device: For the device TCTI, the TPM character device file for use by
277         the device TCTI can be specified.  The default is /dev/tpm0.
278
279         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
280         vice:/dev/tpm0”
281
282mssim:  For  the  mssim  TCTI, the domain name or IP address and port
283         number used by the simulator  can  be  specified.   The  default  are
284         127.0.0.1 and 2321.
285
286         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
287         TI=“mssim:host=localhost,port=2321”
288
289abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
290         ries  of  simple  key value pairs separated by a `,' character.  Each
291         key and value string are separated by a `=' character.
292
293         • TCTI abrmd supports two keys:
294
295           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
296              string).
297
298           2. `bus_type' : The type of the dbus instance (a string) limited to
299              `session' and `system'.
300
301         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
302         ample.FooBar:
303
304                \--tcti=tabrmd:bus_name=com.example.FooBar
305
306         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
307         sion:
308
309                \--tcti:bus_type=session
310
311         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
312         ules.
313

EXAMPLES

315       Associate  auth  value of a sealing object to the owner hierarchy pass‐
316       word.  * Start a trial auth session  and  run  tpm2_policysecret(1)  to
317       create  policy that can only be satisfied if owner hierarchy auth value
318       is supplied.  * Start a real policy session and provide the owner hier‐
319       archy  auth  value.  * Provide the session input where in the policyse‐
320       cret for owner hierarchy auth was satisfied to the unseal tool.   *  If
321       the policy was satisfied unsealing should succeed.
322
323   Generate a policy that binds to the secret of the owner hiearchy
324              tpm2_startauthsession -S session.ctx
325
326              tpm2_policysecret -S session.ctx -c o -L secret.policy
327
328              tpm2_flushcontext session.ctx
329
330   Create a TPM object using the policy
331              tpm2_createprimary -Q -C o -g sha256 -G rsa -c prim.ctx
332
333              tpm2_create -Q -g sha256 -u sealing_key.pub -r sealing_key.priv -i- \
334                -C prim.ctx -L secret.policy <<< "SEALED-SECRET"
335
336              tpm2_load -C prim.ctx -u sealing_key.pub -r sealing_key.priv \
337                -c sealing_key.ctx
338
339   Satisfy the policy and unseal the secret
340              tpm2_startauthsession --policy-session -S session.ctx
341
342              tpm2_policysecret -S session.ctx -c o -L secret.policy
343
344              tpm2_unseal -p "session:session.ctx" -c sealing_key.ctx
345              SEALED-SECRET
346
347              tpm2_flushcontext session.ctx
348

Returns

350       Tools can return any of the following codes:
351
352       • 0 - Success.
353
354       • 1 - General non-specific error.
355
356       • 2 - Options handling error.
357
358       • 3 - Authentication error.
359
360       • 4 - TCTI related error.
361
362       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
363

Limitations

365       It  expects  a session to be already established via tpm2_startauthses‐
366       sion(1) and requires one of the following:
367
368       • direct device access
369
370       • extended session support with tpm2-abrmd.
371
372       Without it, most resource managers will not save session state  between
373       command invocations.
374

BUGS

376       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
377

HELP

379       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
380       fo/tpm2)
381
382
383
384tpm2-tools                                                tpm2_policysecret(1)
Impressum