1tpm2_policysigned(1) General Commands Manual tpm2_policysigned(1)
2
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
11 tpm2_policysigned [OPTIONS]
12
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
20 · -L, --policy=FILE:
21 File to save the compounded policy digest.
23 · -S, --session=FILE:
25 The policy session file generated via the -S option to tpm2_star‐
27 tauthsession(1).
28 · -c, --key-context=OBJECT:
30 Context object for the key context used for the operation. Either a
32 file or a handle number. See section "Context Object Format".
33 · -g, --hash-algorithm=ALGORITHM:
35 The hash algorithm used to digest the message.
37 · -s, --signature=FILE:
39 The input signature file of the signature to be validated.
41 · -f, --format=FORMAT:
43 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 · -t, --expiration=NATURAL_NUMBER:
50 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 · --ticket=FILE:
58 The ticket file to record the authorization ticket structure.
60 · --timeout=FILE:
62 The file path to record the timeout structure returned.
64 · -q, --qualification=FILE_OR_HEX_STR:
66 Optional, the policy qualifier data that the signer can choose to in‐
68 clude in the signature. Can be either a hex string or path.
69 · -x, --nonce-tpm:
71 Enable the comparison of the current session's nonceTPM to ensure the
73 validity of the policy authorization is limited to the current ses‐
74 sion.
75 References
78 This collection of options are common to many programs and provide in‐
79 formation that many users may expect.
80 · -h, --help=[man|no-man]: Display the tools manpage. By default, it
82 attempts to invoke the manpager for the tool, however, on failure
83 will output a short tool summary. This is the same behavior if the
84 "man" option argument is specified, however if explicit "man" is re‐
85 quested, the tool will provide errors from man on stderr. If the
86 "no-man" option if specified, or the manpager fails, the short op‐
87 tions will be output to stdout.
88 To successfully use the manpages feature requires the manpages to be
90 installed or on MANPATH, See man(1) for more details.
91 · -v, --version: Display version information for this tool, supported
93 tctis and exit.
94 · -V, --verbose: Increase the information that the tool prints to the
96 console during its execution. When using this option the file and
97 line number are printed.
98 · -Q, --quiet: Silence normal tool output to stdout.
100 · -Z, --enable-errata: Enable the application of errata fixups. Useful
102 if an errata fixup needs to be applied to commands sent to the TPM.
103 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
104 formation many users may expect.
105
107 The TCTI or "Transmission Interface" is the communication mechanism
108 with the TPM. TCTIs can be changed for communication with TPMs across
109 different mediums.
110 To control the TCTI, the tools respect:
112 1. The command line option -T or --tcti
114 2. The environment variable: TPM2TOOLS_TCTI.
116 Note: The command line option always overrides the environment vari‐
118 able.
119 The current known TCTIs are:
121 · tabrmd - The resource manager, called tabrmd
123 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
124 abrmd as a tcti name are synonymous.
125 · mssim - Typically used for communicating to the TPM software simula‐
127 tor.
128 · device - Used when talking directly to a TPM device file.
130 · none - Do not initalize a connection with the TPM. Some tools allow
132 for off-tpm options and thus support not using a TCTI. Tools that do
133 not support it will error when attempted to be used without a TCTI
134 connection. Does not support ANY options and MUST BE presented as
135 the exact text of "none".
136 The arguments to either the command line option or the environment
138 variable are in the form:
139 <tcti-name>:<tcti-option-config>
141 Specifying an empty string for either the <tcti-name> or <tcti-op‐
143 tion-config> results in the default being used for that portion respec‐
144 tively.
145 TCTI Defaults
147 When a TCTI is not specified, the default TCTI is searched for using
148 dlopen(3) semantics. The tools will search for tabrmd, device and
149 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
150 what TCTI will be chosen as the default by using the -v option to print
151 the version information. The "default-tcti" key-value pair will indi‐
152 cate which of the aforementioned TCTIs is the default.
153 Custom TCTIs
155 Any TCTI that implements the dynamic TCTI interface can be loaded. The
156 tools internally use dlopen(3), and the raw tcti-name value is used for
157 the lookup. Thus, this could be a path to the shared library, or a li‐
158 brary name as understood by dlopen(3) semantics.
159
161 This collection of options are used to configure the various known TCTI
162 modules available:
163 · device: For the device TCTI, the TPM character device file for use by
165 the device TCTI can be specified. The default is /dev/tpm0.
166 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
168 vice:/dev/tpm0"
169 · mssim: For the mssim TCTI, the domain name or IP address and port
171 number used by the simulator can be specified. The default are
172 127.0.0.1 and 2321.
173 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
175 TI="mssim:host=localhost,port=2321"
176 · abrmd: For the abrmd TCTI, the configuration string format is a se‐
178 ries of simple key value pairs separated by a ',' character. Each
179 key and value string are separated by a '=' character.
180 · TCTI abrmd supports two keys:
182 1. 'bus_name' : The name of the tabrmd service on the bus (a
184 string).
185 2. 'bus_type' : The type of the dbus instance (a string) limited to
187 'session' and 'system'.
188 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
190 ample.FooBar:
191 \--tcti=tabrmd:bus_name=com.example.FooBar
193 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
195 sion:
196 \--tcti:bus_type=session
198 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
200 ules.
201
203 Authorize a TPM operation on an object whose authorization is bound to
204 specific signing authority.
205 Create the signing authority
207 openssl genrsa -out private.pem 2048
208 openssl rsa -in private.pem -outform PEM -pubout -out public.pem
210 Generate signature with nonceTPM, cpHashA, policyRef and expiration
212 set to 0
213 echo "00 00 00 00" | xxd -r -p | \
215 openssl dgst -sha256 -sign private.pem -out signature.dat
216 Load the verification key and Create the policysigned policy
218 tpm2_loadexternal -C o -G rsa -u public.pem -c signing_key.ctx
219 tpm2_startauthsession -S session.ctx
221 tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
223 -c signing_key.ctx -L policy.signed
224 tpm2_flushcontext session.ctx
226 Create a sealing object to use the policysigned
228 ``bash echo "plaintext" > secret.data
229 tpm2_createprimary -C o -c prim.ctx
231 tpm2_create -u key.pub -r sealing_key.priv -c sealing_key.ctx -C
233 prim.ctx
234 -i secret.data -L policy.signed ```
235 Satisfy the policy and unseal secret
237 tpm2_startauthsession -S session.ctx --policy-session
238 tpm2_policysigned -S session.ctx -g sha256 -s signature.dat -f rsassa \
240 -c signing_key.ctx -L policy.signed
241 tpm2_unseal -p session:session.ctx -c sealing_key.ctx
243 tpm2_flushcontext session.ctx
245
247 Tools can return any of the following codes:
248 · 0 - Success.
250 · 1 - General non-specific error.
252 · 2 - Options handling error.
254 · 3 - Authentication error.
256 · 4 - TCTI related error.
258 · 5 - Non supported scheme. Applicable to tpm2_testparams.
260
262 It expects a session to be already established via tpm2_startauthses‐
263 sion(1) and requires one of the following:
264 · direct device access
266 · extended session support with tpm2-abrmd.
268 Without it, most resource managers will not save session state between
270 command invocations.
271
273 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
274
276 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
277tpm2-tools tpm2_policysigned(1)