1tpm2_activatecredential(1) General Commands Manual tpm2_activatecredential(1)
2
6 tpm2_activatecredential(1) - Enables access to the credential qualifier
7 to recover the credential secret.
8
10 tpm2_activatecredential [OPTIONS]
11
13 tpm2_activatecredential(1) - Enables the association of a credential
14 with an object in a way that ensures that the TPM has validated the pa‐
15 rameters of the credentialed object. In an attestation scheme , this
16 guarantees the registrar that the attestation key belongs to the TPM
17 with a qualified parent key in the TPM.
18
20 • -c, --credentialedkey-context=OBJECT:
21 Object associated with the created certificate by CA.
23 • -C, --credentialkey-context=OBJECT:
25 The loaded object used to decrypt the random seed.
27 • -p, --credentialedkey-auth=AUTH:
29 The auth value of the credentialed object specified with -c.
31 • -P, --credentialkey-auth=AUTH:
33 The auth value of the credential object specified with -C.
35 • -i, --credential-blob=FILE:
37 The input file path containing the credential blob and secret created
39 with the tpm2_makecredential(1) tool.
40 • -o, --certinfo-data=FILE:
42 The output file path to save the decrypted credential secret informa‐
44 tion.
45 • --cphash=FILE
47 File path to record the hash of the command parameters. This is com‐
49 monly termed as cpHash. NOTE: When this option is selected, The tool
50 will not actually execute the command, it simply returns a cpHash,
51 unless rphash is also required.
52 • --rphash=FILE
54 File path to record the hash of the response parameters. This is
56 commonly termed as rpHash.
57 • -S, --session=FILE:
59 The session created using tpm2_startauthsession. This can be used to
61 specify an auxiliary session for auditing and or encryption/decryp‐
62 tion of the parameters.
63 References
66 The type of a context object, whether it is a handle or file name, is
67 determined according to the following logic in-order:
68 • If the argument is a file path, then the file is loaded as a restored
70 TPM transient object.
71 • If the argument is a prefix match on one of:
73 • owner: the owner hierarchy
75 • platform: the platform hierarchy
77 • endorsement: the endorsement hierarchy
79 • lockout: the lockout control persistent object
81 • If the argument argument can be loaded as a number it will be treat
83 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
84
86 Authorization for use of an object in TPM2.0 can come in 3 different
87 forms: 1. Password 2. HMAC 3. Sessions
88 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
90 fied”.
91 Passwords
93 Passwords are interpreted in the following forms below using prefix
94 identifiers.
95 Note: By default passwords are assumed to be in the string form when
97 they do not have a prefix.
98 String
100 A string password, specified by prefix “str:” or it’s absence (raw
101 string without prefix) is not interpreted, and is directly used for au‐
102 thorization.
103 Examples
105 foobar
106 str:foobar
107 Hex-string
109 A hex-string password, specified by prefix “hex:” is converted from a
110 hexidecimal form into a byte array form, thus allowing passwords with
111 non-printable and/or terminal un-friendly characters.
112 Example
114 hex:0x1122334455667788
115 File
117 A file based password, specified be prefix “file:” should be the path
118 of a file containing the password to be read by the tool or a “-” to
119 use stdin. Storing passwords in files prevents information leakage,
120 passwords passed as options can be read from the process list or common
121 shell history features.
122 Examples
124 # to use stdin and be prompted
125 file:-
126 # to use a file from a path
128 file:path/to/password/file
129 # to echo a password via stdin:
131 echo foobar | tpm2_tool -p file:-
132 # to use a bash here-string via stdin:
134 tpm2_tool -p file:- <<< foobar
136 Sessions
138 When using a policy session to authorize the use of an object, prefix
139 the option argument with the session keyword. Then indicate a path to
140 a session file that was created with tpm2_startauthsession(1). Option‐
141 ally, if the session requires an auth value to be sent with the session
142 handle (eg policy password), then append a + and a string as described
143 in the Passwords section.
144 Examples
146 To use a session context file called session.ctx.
147 session:session.ctx
149 To use a session context file called session.ctx AND send the authvalue
151 mypassword.
152 session:session.ctx+mypassword
154 To use a session context file called session.ctx AND send the HEX auth‐
156 value 0x11223344.
157 session:session.ctx+hex:11223344
159 PCR Authorizations
161 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
162 language. The PCR minilanguage is as follows:
163 <pcr-spec>=<raw-pcr-file>
164 The PCR spec is documented in in the section “PCR bank specifiers”.
166 The raw-pcr-file is an optional argument that contains the output of
168 the raw PCR contents as returned by tpm2_pcrread(1).
169 PCR bank specifiers (pcr.md)
171 Examples
173 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
174 er of:
175 pcr:sha256:0,1,2,3
177 specifying AUTH.
179
181 This collection of options are common to many programs and provide in‐
182 formation that many users may expect.
183 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
185 attempts to invoke the manpager for the tool, however, on failure
186 will output a short tool summary. This is the same behavior if the
187 “man” option argument is specified, however if explicit “man” is re‐
188 quested, the tool will provide errors from man on stderr. If the
189 “no-man” option if specified, or the manpager fails, the short op‐
190 tions will be output to stdout.
191 To successfully use the manpages feature requires the manpages to be
193 installed or on MANPATH, See man(1) for more details.
194 • -v, --version: Display version information for this tool, supported
196 tctis and exit.
197 • -V, --verbose: Increase the information that the tool prints to the
199 console during its execution. When using this option the file and
200 line number are printed.
201 • -Q, --quiet: Silence normal tool output to stdout.
203 • -Z, --enable-errata: Enable the application of errata fixups. Useful
205 if an errata fixup needs to be applied to commands sent to the TPM.
206 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
207 formation many users may expect.
208
210 The TCTI or “Transmission Interface” is the communication mechanism
211 with the TPM. TCTIs can be changed for communication with TPMs across
212 different mediums.
213 To control the TCTI, the tools respect:
215 1. The command line option -T or --tcti
217 2. The environment variable: TPM2TOOLS_TCTI.
219 Note: The command line option always overrides the environment vari‐
221 able.
222 The current known TCTIs are:
224 • tabrmd - The resource manager, called tabrmd
226 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
227 abrmd as a tcti name are synonymous.
228 • mssim - Typically used for communicating to the TPM software simula‐
230 tor.
231 • device - Used when talking directly to a TPM device file.
233 • none - Do not initalize a connection with the TPM. Some tools allow
235 for off-tpm options and thus support not using a TCTI. Tools that do
236 not support it will error when attempted to be used without a TCTI
237 connection. Does not support ANY options and MUST BE presented as
238 the exact text of “none”.
239 The arguments to either the command line option or the environment
241 variable are in the form:
242 <tcti-name>:<tcti-option-config>
244 Specifying an empty string for either the <tcti-name> or <tcti-op‐
246 tion-config> results in the default being used for that portion respec‐
247 tively.
248 TCTI Defaults
250 When a TCTI is not specified, the default TCTI is searched for using
251 dlopen(3) semantics. The tools will search for tabrmd, device and
252 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
253 what TCTI will be chosen as the default by using the -v option to print
254 the version information. The “default-tcti” key-value pair will indi‐
255 cate which of the aforementioned TCTIs is the default.
256 Custom TCTIs
258 Any TCTI that implements the dynamic TCTI interface can be loaded. The
259 tools internally use dlopen(3), and the raw tcti-name value is used for
260 the lookup. Thus, this could be a path to the shared library, or a li‐
261 brary name as understood by dlopen(3) semantics.
262
264 This collection of options are used to configure the various known TCTI
265 modules available:
266 • device: For the device TCTI, the TPM character device file for use by
268 the device TCTI can be specified. The default is /dev/tpm0.
269 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
271 vice:/dev/tpm0”
272 • mssim: For the mssim TCTI, the domain name or IP address and port
274 number used by the simulator can be specified. The default are
275 127.0.0.1 and 2321.
276 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
278 TI=“mssim:host=localhost,port=2321”
279 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
281 ries of simple key value pairs separated by a `,' character. Each
282 key and value string are separated by a `=' character.
283 • TCTI abrmd supports two keys:
285 1. `bus_name' : The name of the tabrmd service on the bus (a
287 string).
288 2. `bus_type' : The type of the dbus instance (a string) limited to
290 `session' and `system'.
291 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
293 ample.FooBar:
294 \--tcti=tabrmd:bus_name=com.example.FooBar
296 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298 sion:
299 \--tcti:bus_type=session
301 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
303 ules.
304
306 echo "12345678" > secret.data
307 tpm2_createek -Q -c 0x81010001 -G rsa -u ek.pub
309 tpm2_createak -C 0x81010001 -c ak.ctx -G rsa -g sha256 -s rsassa -u ak.pub \
311 -n ak.name -p akpass> ak.out
312 file_size=`stat --printf="%s" ak.name`
314 loaded_key_name=`cat ak.name | xxd -p -c $file_size`
315 tpm2_makecredential -Q -e ek.pub -s secret.data -n $loaded_key_name \
317 -o mkcred.out
318 tpm2_startauthsession --policy-session -S session.ctx
320 tpm2_policysecret -S session.ctx -c e
322 tpm2_activatecredential -Q -c ak.ctx -C 0x81010001 -i mkcred.out \
324 -o actcred.out -p akpass -P"session:session.ctx"
325 tpm2_flushcontext session.ctx
327
329 Tools can return any of the following codes:
330 • 0 - Success.
332 • 1 - General non-specific error.
334 • 2 - Options handling error.
336 • 3 - Authentication error.
338 • 4 - TCTI related error.
340 • 5 - Non supported scheme. Applicable to tpm2_testparams.
342
344 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
345
347 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
348tpm2-tools tpm2_activatecredential(1)