1tpm2_policyauthorize(1) General Commands Manual tpm2_policyauthorize(1)
2
6 tpm2_policyauthorize(1) - Allows for mutable policies by tethering to a
7 signing authority.
8
10 tpm2_policyauthorize [OPTIONS]
11
13 tpm2_policyauthorize(1) - This command allows for policies to change by
14 associating the policy to a signing authority and allowing the policy
15 contents to change.
16 1. If the input session is a trial session this tool generates a policy
18 digest that associates a signing authority’s public key name with
19 the policy being authorized.
20 2. If the input session is real policy session tpm2_policyauthorize(1)
22 looks for a verification ticket from the TPM to attest that the TPM
23 has verified the signature on the policy digest before authorizing
24 the policy in the policy digest.
25
27 • -L, --policy=FILE:
28 File to save the policy digest.
30 • -S, --session=FILE:
32 The policy session file generated via the -S option to tpm2_star‐
34 tauthsession(1).
35 • -i, --input=FILE:
37 The policy digest that has to be authorized.
39 • -q, --qualification=FILE_OR_HEX:
41 The policy qualifier data signed in conjunction with the input policy
43 digest. This is unique data that the signer can choose to include in
44 the signature and can either be a path or hex string.
45 • -n, --name=FILE:
47 File containing the name of the verifying public key. This ties the
49 final policy digest with a signer. This can be retrieved with
50 tpm2_readpublic(1)
51 • -t, --ticket=FILE:
53 The ticket file to record the validation structure. This is generat‐
55 ed with tpm2_verifysignature(1).
56 • --cphash=FILE
58 File path to record the hash of the command parameters. This is com‐
60 monly termed as cpHash. NOTE: When this option is selected, The tool
61 will not actually execute the command, it simply returns a cpHash.
62 References
65 This collection of options are common to many programs and provide in‐
66 formation that many users may expect.
67 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
69 attempts to invoke the manpager for the tool, however, on failure
70 will output a short tool summary. This is the same behavior if the
71 “man” option argument is specified, however if explicit “man” is re‐
72 quested, the tool will provide errors from man on stderr. If the
73 “no-man” option if specified, or the manpager fails, the short op‐
74 tions will be output to stdout.
75 To successfully use the manpages feature requires the manpages to be
77 installed or on MANPATH, See man(1) for more details.
78 • -v, --version: Display version information for this tool, supported
80 tctis and exit.
81 • -V, --verbose: Increase the information that the tool prints to the
83 console during its execution. When using this option the file and
84 line number are printed.
85 • -Q, --quiet: Silence normal tool output to stdout.
87 • -Z, --enable-errata: Enable the application of errata fixups. Useful
89 if an errata fixup needs to be applied to commands sent to the TPM.
90 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
91 formation many users may expect.
92
94 The TCTI or “Transmission Interface” is the communication mechanism
95 with the TPM. TCTIs can be changed for communication with TPMs across
96 different mediums.
97 To control the TCTI, the tools respect:
99 1. The command line option -T or --tcti
101 2. The environment variable: TPM2TOOLS_TCTI.
103 Note: The command line option always overrides the environment vari‐
105 able.
106 The current known TCTIs are:
108 • tabrmd - The resource manager, called tabrmd
110 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
111 abrmd as a tcti name are synonymous.
112 • mssim - Typically used for communicating to the TPM software simula‐
114 tor.
115 • device - Used when talking directly to a TPM device file.
117 • none - Do not initalize a connection with the TPM. Some tools allow
119 for off-tpm options and thus support not using a TCTI. Tools that do
120 not support it will error when attempted to be used without a TCTI
121 connection. Does not support ANY options and MUST BE presented as
122 the exact text of “none”.
123 The arguments to either the command line option or the environment
125 variable are in the form:
126 <tcti-name>:<tcti-option-config>
128 Specifying an empty string for either the <tcti-name> or <tcti-op‐
130 tion-config> results in the default being used for that portion respec‐
131 tively.
132 TCTI Defaults
134 When a TCTI is not specified, the default TCTI is searched for using
135 dlopen(3) semantics. The tools will search for tabrmd, device and
136 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
137 what TCTI will be chosen as the default by using the -v option to print
138 the version information. The “default-tcti” key-value pair will indi‐
139 cate which of the aforementioned TCTIs is the default.
140 Custom TCTIs
142 Any TCTI that implements the dynamic TCTI interface can be loaded. The
143 tools internally use dlopen(3), and the raw tcti-name value is used for
144 the lookup. Thus, this could be a path to the shared library, or a li‐
145 brary name as understood by dlopen(3) semantics.
146
148 This collection of options are used to configure the various known TCTI
149 modules available:
150 • device: For the device TCTI, the TPM character device file for use by
152 the device TCTI can be specified. The default is /dev/tpm0.
153 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
155 vice:/dev/tpm0”
156 • mssim: For the mssim TCTI, the domain name or IP address and port
158 number used by the simulator can be specified. The default are
159 127.0.0.1 and 2321.
160 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
162 TI=“mssim:host=localhost,port=2321”
163 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
165 ries of simple key value pairs separated by a `,' character. Each
166 key and value string are separated by a `=' character.
167 • TCTI abrmd supports two keys:
169 1. `bus_name' : The name of the tabrmd service on the bus (a
171 string).
172 2. `bus_type' : The type of the dbus instance (a string) limited to
174 `session' and `system'.
175 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
177 ample.FooBar:
178 \--tcti=tabrmd:bus_name=com.example.FooBar
180 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
182 sion:
183 \--tcti:bus_type=session
185 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
187 ules.
188
190 Starts a trial session, builds a PCR policy. This PCR policy digest is
191 then an input to the tpm2_policyauthorize(1) along with policy qualifi‐
192 er data and a signer public. The resultant policy digest is then used
193 in creation of objects.
194 Subsequently when the PCR change and so does the PCR policy digest, the
196 actual policy digest from the tpm2_policyauthorize(1) used in creation
197 of the object will not change. At runtime the new PCR policy needs to
198 be satisfied along with verification of the signature on the PCR policy
199 digest using tpm2_policyauthorize(1)
200 Create a signing authority
202 openssl genrsa -out signing_key_private.pem 2048
203 openssl rsa -in signing_key_private.pem -out signing_key_public.pem -pubout
205 tpm2_loadexternal -G rsa -C o -u signing_key_public.pem -c signing_key.ctx -n signing_key.name
207 Create the authorize policy digest
209 tpm2_startauthsession -S session.ctx
210 tpm2_policyauthorize -S session.ctx -L authorized.policy -n signing_key.name
212 tpm2_flushcontext session.ctx
214 Create a policy to be authorized like a PCR policy
216 tpm2_pcrread -opcr0.sha256 sha256:0
217 tpm2_startauthsession -S session.ctx
219 tpm2_policypcr -S session.ctx -l sha256:0 -f pcr0.sha256 -L pcr.policy_desired
221 tpm2_flushcontext session.ctx
223 Sign the policy
225 openssl dgst -sha256 -sign signing_key_private.pem -out pcr.signature pcr.policy_desired
226 Create a TPM object like a sealing object with the authorized policy based
228 authentication
229 tpm2_createprimary -C o -g sha256 -G rsa -c prim.ctx
230 tpm2_create -g sha256 -u sealing_pubkey.pub -r sealing_prikey.pub -i- -C prim.ctx -L authorized.policy <<< "secret to seal"
232 Verify the desired policy digest comes from the signing authority, read the
234 actual value of PCR and check that read policy and desired policy are
235 equal.
236 tpm2_verifysignature -c signing_key.ctx -g sha256 -m pcr.policy_desired -s pcr.signature -t verification.tkt -f rsassa
237 tpm2_startauthsession \--policy-session -S session.ctx
239 tpm2_policypcr -S session.ctx -l sha256:0 -L pcr.policy_read
241 tpm2_policyauthorize -S session.ctx -L authorized.policy -i pcr.policy_desired -n signing_key.name -t verification.tkt
243 tpm2_load -C prim.ctx -u sealing_pubkey.pub -r sealing_prikey.pub -c sealing_key.ctx
245 unsealed=$(tpm2_unseal -p"session:session.ctx" -c sealing_key.ctx)
247 echo $unsealed
249 tpm2_flushcontext session.ctx
251
253 Tools can return any of the following codes:
254 • 0 - Success.
256 • 1 - General non-specific error.
258 • 2 - Options handling error.
260 • 3 - Authentication error.
262 • 4 - TCTI related error.
264 • 5 - Non supported scheme. Applicable to tpm2_testparams.
266
268 It expects a session to be already established via tpm2_startauthses‐
269 sion(1) and requires one of the following:
270 • direct device access
272 • extended session support with tpm2-abrmd.
274 Without it, most resource managers will not save session state between
276 command invocations.
277
279 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
280
282 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
283 fo/tpm2)
284tpm2-tools tpm2_policyauthorize(1)