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       · ARGUMENT  the  command line argument specifies the AUTH to be set for
38         the object specified with -c.
39
40   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

157       This collection of options are common to many programs and provide  in‐
158       formation that many users may expect.
159
160       · -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
161         attempts to invoke the manpager for the  tool,  however,  on  failure
162         will  output  a short tool summary.  This is the same behavior if the
163         "man" option argument is specified, however if explicit "man" is  re‐
164         quested,  the  tool  will  provide errors from man on stderr.  If the
165         "no-man" option if specified, or the manpager fails,  the  short  op‐
166         tions will be output to stdout.
167
168         To  successfully use the manpages feature requires the manpages to be
169         installed or on MANPATH, See man(1) for more details.
170
171       · -v, --version: Display version information for this  tool,  supported
172         tctis and exit.
173
174       · -V,  --verbose:  Increase the information that the tool prints to the
175         console during its execution.  When using this option  the  file  and
176         line number are printed.
177
178       · -Q, --quiet: Silence normal tool output to stdout.
179
180       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
181         if an errata fixup needs to be applied to commands sent to  the  TPM.
182         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
183         formation many users may expect.
184

TCTI Configuration

186       The TCTI or "Transmission Interface"  is  the  communication  mechanism
187       with  the TPM.  TCTIs can be changed for communication with TPMs across
188       different mediums.
189
190       To control the TCTI, the tools respect:
191
192       1. The command line option -T or --tcti
193
194       2. The environment variable: TPM2TOOLS_TCTI.
195
196       Note: The command line option always overrides  the  environment  vari‐
197       able.
198
199       The current known TCTIs are:
200
201       · tabrmd      -     The     resource     manager,     called     tabrmd
202         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
203         abrmd as a tcti name are synonymous.
204
205       · mssim  - Typically used for communicating to the TPM software simula‐
206         tor.
207
208       · device - Used when talking directly to a TPM device file.
209
210       · none - Do not initalize a connection with the TPM.  Some tools  allow
211         for off-tpm options and thus support not using a TCTI.  Tools that do
212         not support it will error when attempted to be used  without  a  TCTI
213         connection.   Does  not  support ANY options and MUST BE presented as
214         the exact text of "none".
215
216       The arguments to either the command  line  option  or  the  environment
217       variable are in the form:
218
219       <tcti-name>:<tcti-option-config>
220
221       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
222       tion-config> results in the default being used for that portion respec‐
223       tively.
224
225   TCTI Defaults
226       When  a  TCTI  is not specified, the default TCTI is searched for using
227       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
228       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
229       what TCTI will be chosen as the default by using the -v option to print
230       the  version information.  The "default-tcti" key-value pair will indi‐
231       cate which of the aforementioned TCTIs is the default.
232
233   Custom TCTIs
234       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
235       tools internally use dlopen(3), and the raw tcti-name value is used for
236       the lookup.  Thus, this could be a path to the shared library, or a li‐
237       brary name as understood by dlopen(3) semantics.
238

TCTI OPTIONS

240       This collection of options are used to configure the various known TCTI
241       modules available:
242
243       · device: For the device TCTI, the TPM character device file for use by
244         the device TCTI can be specified.  The default is /dev/tpm0.
245
246         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI="de‐
247         vice:/dev/tpm0"
248
249       · mssim: For the mssim TCTI, the domain name or  IP  address  and  port
250         number  used  by  the  simulator  can  be specified.  The default are
251         127.0.0.1 and 2321.
252
253         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
254         TI="mssim:host=localhost,port=2321"
255
256       · abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
257         ries of simple key value pairs separated by a  ','  character.   Each
258         key and value string are separated by a '=' character.
259
260         · TCTI abrmd supports two keys:
261
262           1. 'bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
263              string).
264
265           2. 'bus_type' : The type of the dbus instance (a string) limited to
266              'session' and 'system'.
267
268         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
269         ample.FooBar:
270
271         \--tcti=tabrmd:bus_name=com.example.FooBar
272
273         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
274         sion:
275
276         \--tcti:bus_type=session
277
278         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
279         ules.
280

EXAMPLES

282       Associate auth value of a sealing object to the owner  hierarchy  pass‐
283       word.   *  Start  a  trial auth session and run tpm2_policysecret(1) to
284       create policy that can only be satisfied if owner hierarchy auth  value
285       is supplied.  * Start a real policy session and provide the owner hier‐
286       archy auth value.  * Provide the session input where in  the  policyse‐
287       cret  for  owner hierarchy auth was satisfied to the unseal tool.  * If
288       the policy was satisfied unsealing should succeed.
289
290   Generate a policy that binds to the secret of the owner hiearchy
291              tpm2_startauthsession -S session.ctx
292
293              tpm2_policysecret -S session.ctx -c o -L secret.policy
294
295              tpm2_flushcontext session.ctx
296
297   Create a TPM object using the policy
298              tpm2_createprimary -Q -C o -g sha256 -G rsa -c prim.ctx
299
300              tpm2_create -Q -g sha256 -u sealing_key.pub -r sealing_key.priv -i- \
301                -C prim.ctx -L secret.policy <<< "SEALED-SECRET"
302
303              tpm2_load -C prim.ctx -u sealing_key.pub -r sealing_key.priv \
304                -c sealing_key.ctx
305
306   Satisfy the policy and unseal the secret
307              tpm2_startauthsession --policy-session -S session.ctx
308
309              tpm2_policysecret -S session.ctx -c o -L secret.policy
310
311              tpm2_unseal -p "session:session.ctx" -c sealing_key.ctx
312              SEALED-SECRET
313
314              tpm2_flushcontext session.ctx
315

Returns

317       Tools can return any of the following codes:
318
319       · 0 - Success.
320
321       · 1 - General non-specific error.
322
323       · 2 - Options handling error.
324
325       · 3 - Authentication error.
326
327       · 4 - TCTI related error.
328
329       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
330

Limitations

332       It expects a session to be already established  via  tpm2_startauthses‐
333       sion(1) and requires one of the following:
334
335       · direct device access
336
337       · extended session support with tpm2-abrmd.
338
339       Without  it, most resource managers will not save session state between
340       command invocations.
341

BUGS

343       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
344

HELP

346       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
347
348
349
350tpm2-tools                                                tpm2_policysecret(1)