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

NAME

6       tpm2_policysigned(1) - Enables policy authorization by verifying signa‐
7       ture of optional TPM2 parameters.  The  signature  is  generated  by  a
8       signing authority.
9

SYNOPSIS

11       tpm2_policysigned [OPTIONS]
12

DESCRIPTION

14       tpm2_policysigned(1) - Enables policy authorization by verifying signa‐
15       ture of optional TPM2 parameters.  The  signature  is  generated  by  a
16       signing  authority.   The  optional TPM2 parameters being cpHashA, non‐
17       ceTPM, policyRef and expiration.
18

OPTIONS

20-L, --policy=FILE:
21
22         File to save the compounded policy digest.
23
24-S, --session=FILE:
25
26         The policy session file generated via the  -S  option  to  tpm2_star‐
27         tauthsession(1).
28
29-c, --key-context=OBJECT:
30
31         Context  object for the key context used for the operation.  Either a
32         file or a handle number.  See section “Context Object Format”.
33
34-g, --hash-algorithm=ALGORITHM:
35
36         The hash algorithm used to digest the message.
37
38-s, --signature=FILE:
39
40         The input signature file of the signature to be validated.
41
42-f, --format=FORMAT:
43
44         Set the input signature file to a specified format.  The  default  is
45         the  tpm2.0 TPMT_SIGNATURE data format, however different schemes can
46         be selected if the data came from an external  source  like  OpenSSL.
47         The tool currently supports rsassa and ecdsa.
48
49-t, --expiration=NATURAL_NUMBER:
50
51         Set the expiration time of the policy in seconds.  In absence of non‐
52         ceTPM the expiration time is the policy timeout value.  If expiration
53         is a negative value an authorization ticket is additionally returned.
54         If expiration value is 0 then the policy does not have a  time  limit
55         on the authorization.
56
57--cphash-input=FILE:
58
59         The  command parameter hash (cpHash), enforcing the TPM command to be
60         authorized as well as its handle and parameter values.
61
62--ticket=FILE:
63
64         The ticket file to record the authorization ticket structure.
65
66--timeout=FILE:
67
68         The file path to record the timeout structure returned.
69
70-q, --qualification=FILE_OR_HEX_STR:
71
72         Optional, the policy qualifier data that the signer can choose to in‐
73         clude in the signature.  Can be either a hex string or path.
74
75-x, --nonce-tpm:
76
77         Enable the comparison of the current session’s nonceTPM to ensure the
78         validity of the policy authorization is limited to the  current  ses‐
79         sion.
80
81   References

COMMON OPTIONS

83       This  collection of options are common to many programs and provide in‐
84       formation that many users may expect.
85
86-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
87         attempts  to  invoke  the  manpager for the tool, however, on failure
88         will output a short tool summary.  This is the same behavior  if  the
89         “man”  option argument is specified, however if explicit “man” is re‐
90         quested, the tool will provide errors from man  on  stderr.   If  the
91         “no-man”  option  if  specified, or the manpager fails, the short op‐
92         tions will be output to stdout.
93
94         To successfully use the manpages feature requires the manpages to  be
95         installed or on MANPATH, See man(1) for more details.
96
97-v,  --version:  Display version information for this tool, supported
98         tctis and exit.
99
100-V, --verbose: Increase the information that the tool prints  to  the
101         console  during  its  execution.  When using this option the file and
102         line number are printed.
103
104-Q, --quiet: Silence normal tool output to stdout.
105
106-Z, --enable-errata: Enable the application of errata fixups.  Useful
107         if  an  errata fixup needs to be applied to commands sent to the TPM.
108         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
109         formation many users may expect.
110

TCTI Configuration

112       The  TCTI  or  “Transmission  Interface” is the communication mechanism
113       with the TPM.  TCTIs can be changed for communication with TPMs  across
114       different mediums.
115
116       To control the TCTI, the tools respect:
117
118       1. The command line option -T or --tcti
119
120       2. The environment variable: TPM2TOOLS_TCTI.
121
122       Note:  The  command  line option always overrides the environment vari‐
123       able.
124
125       The current known TCTIs are:
126
127       • tabrmd     -     The     resource     manager,     called      tabrmd
128         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
129         abrmd as a tcti name are synonymous.
130
131       • mssim - Typically used for communicating to the TPM software  simula‐
132         tor.
133
134       • device - Used when talking directly to a TPM device file.
135
136       • none  - Do not initalize a connection with the TPM.  Some tools allow
137         for off-tpm options and thus support not using a TCTI.  Tools that do
138         not  support  it  will error when attempted to be used without a TCTI
139         connection.  Does not support ANY options and MUST  BE  presented  as
140         the exact text of “none”.
141
142       The  arguments  to  either  the  command line option or the environment
143       variable are in the form:
144
145       <tcti-name>:<tcti-option-config>
146
147       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
148       tion-config> results in the default being used for that portion respec‐
149       tively.
150
151   TCTI Defaults
152       When a TCTI is not specified, the default TCTI is  searched  for  using
153       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
154       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
155       what TCTI will be chosen as the default by using the -v option to print
156       the version information.  The “default-tcti” key-value pair will  indi‐
157       cate which of the aforementioned TCTIs is the default.
158
159   Custom TCTIs
160       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
161       tools internally use dlopen(3), and the raw tcti-name value is used for
162       the lookup.  Thus, this could be a path to the shared library, or a li‐
163       brary name as understood by dlopen(3) semantics.
164

TCTI OPTIONS

166       This collection of options are used to configure the various known TCTI
167       modules available:
168
169device: For the device TCTI, the TPM character device file for use by
170         the device TCTI can be specified.  The default is /dev/tpm0.
171
172         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
173         vice:/dev/tpm0”
174
175mssim:  For  the  mssim  TCTI, the domain name or IP address and port
176         number used by the simulator  can  be  specified.   The  default  are
177         127.0.0.1 and 2321.
178
179         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
180         TI=“mssim:host=localhost,port=2321”
181
182abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
183         ries  of  simple  key value pairs separated by a `,' character.  Each
184         key and value string are separated by a `=' character.
185
186         • TCTI abrmd supports two keys:
187
188           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
189              string).
190
191           2. `bus_type' : The type of the dbus instance (a string) limited to
192              `session' and `system'.
193
194         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
195         ample.FooBar:
196
197                \--tcti=tabrmd:bus_name=com.example.FooBar
198
199         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
200         sion:
201
202                \--tcti:bus_type=session
203
204         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
205         ules.
206

EXAMPLES

208       Authorize  a TPM operation on an object whose authorization is bound to
209       specific signing authority.
210
211   Create the signing authority
212              openssl genrsa -out private.pem 2048
213
214              openssl rsa -in private.pem -outform PEM -pubout -out public.pem
215
216   Generate signature with nonceTPM, cpHashA, policyRef and expiration set  to
217       0
218              echo "00 00 00 00" | xxd -r -p | \
219              openssl dgst -sha256 -sign private.pem -out signature.dat
220
221   Load the verification key and Create the policysigned policy
222              tpm2_loadexternal -C o -G rsa -u public.pem -c signing_key.ctx
223
224              tpm2_startauthsession -S session.ctx
225
226              tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
227              -c signing_key.ctx -L policy.signed
228
229              tpm2_flushcontext session.ctx
230
231   Create a sealing object to use the policysigned
232              echo "plaintext" > secret.data
233
234              tpm2_createprimary -C o -c prim.ctx
235
236              tpm2_create -u key.pub -r sealing_key.priv -c sealing_key.ctx -C prim.ctx \
237              -i secret.data -L policy.signed
238
239   Satisfy the policy and unseal secret
240              tpm2_startauthsession -S session.ctx --policy-session
241
242              tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
243              -c signing_key.ctx -L policy.signed
244
245              tpm2_unseal -p session:session.ctx -c sealing_key.ctx
246
247              tpm2_flushcontext session.ctx
248

Returns

250       Tools can return any of the following codes:
251
252       • 0 - Success.
253
254       • 1 - General non-specific error.
255
256       • 2 - Options handling error.
257
258       • 3 - Authentication error.
259
260       • 4 - TCTI related error.
261
262       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
263

Limitations

265       It  expects  a session to be already established via tpm2_startauthses‐
266       sion(1) and requires one of the following:
267
268       • direct device access
269
270       • extended session support with tpm2-abrmd.
271
272       Without it, most resource managers will not save session state  between
273       command invocations.
274

BUGS

276       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
277

HELP

279       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
280       fo/tpm2)
281
282
283
284tpm2-tools                                                tpm2_policysigned(1)
Impressum