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

NAME

6       tpm2_activatecredential(1) - Enables access to the credential qualifier
7       to recover the credential secret.
8

SYNOPSIS

10       tpm2_activatecredential [OPTIONS]
11

DESCRIPTION

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

OPTIONS

20-c, --credentialedkey-context=OBJECT:
21
22         Object associated with the created certificate by CA.
23
24-C, --credentialkey-context=OBJECT:
25
26         The loaded object used to decrypt the random seed.
27
28-p, --credentialedkey-auth=AUTH:
29
30         The auth value of the credentialed object specified with -c.
31
32-P, --credentialkey-auth=AUTH:
33
34         The auth value of the credential object specified with -C.
35
36-i, --credential-blob=FILE:
37
38         The input file path containing the credential blob and secret created
39         with the tpm2_makecredential(1) tool.
40
41-o, --certinfo-data=FILE:
42
43         The output file path to save the decrypted credential secret informa‐
44         tion.
45
46--cphash=FILE
47
48         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
53--rphash=FILE
54
55         File  path  to  record  the hash of the response parameters.  This is
56         commonly termed as rpHash.
57
58-S, --session=FILE:
59
60         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
64   References

Context Object Format

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
69       • If the argument is a file path, then the file is loaded as a restored
70         TPM transient object.
71
72       • If the argument is a prefix match on one of:
73
74         • owner: the owner hierarchy
75
76         • platform: the platform hierarchy
77
78         • endorsement: the endorsement hierarchy
79
80         • lockout: the lockout control persistent object
81
82       • 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

Authorization Formatting

86       Authorization  for  use  of an object in TPM2.0 can come in 3 different
87       forms: 1.  Password 2.  HMAC 3.  Sessions
88
89       NOTE: “Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
90       fied”.
91
92   Passwords
93       Passwords  are  interpreted  in  the following forms below using prefix
94       identifiers.
95
96       Note: By default passwords are assumed to be in the  string  form  when
97       they do not have a prefix.
98
99   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
104   Examples
105              foobar
106              str:foobar
107
108   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
113   Example
114              hex:0x1122334455667788
115
116   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
123   Examples
124              # to use stdin and be prompted
125              file:-
126
127              # to use a file from a path
128              file:path/to/password/file
129
130              # to echo a password via stdin:
131              echo foobar | tpm2_tool -p file:-
132
133              # to use a bash here-string via stdin:
134
135              tpm2_tool -p file:- <<< foobar
136
137   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
145   Examples
146       To use a session context file called session.ctx.
147
148              session:session.ctx
149
150       To use a session context file called session.ctx AND send the authvalue
151       mypassword.
152
153              session:session.ctx+mypassword
154
155       To use a session context file called session.ctx AND send the HEX auth‐
156       value 0x11223344.
157
158              session:session.ctx+hex:11223344
159
160   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
165       The PCR spec is documented in in the section “PCR bank specifiers”.
166
167       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
170       PCR bank specifiers (pcr.md)
171
172   Examples
173       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
174       er of:
175
176              pcr:sha256:0,1,2,3
177
178       specifying AUTH.
179

COMMON OPTIONS

181       This collection of options are common to many programs and provide  in‐
182       formation that many users may expect.
183
184-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
192         To  successfully use the manpages feature requires the manpages to be
193         installed or on MANPATH, See man(1) for more details.
194
195-v, --version: Display version information for this  tool,  supported
196         tctis and exit.
197
198-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
202-Q, --quiet: Silence normal tool output to stdout.
203
204-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

TCTI Configuration

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
214       To control the TCTI, the tools respect:
215
216       1. The command line option -T or --tcti
217
218       2. The environment variable: TPM2TOOLS_TCTI.
219
220       Note: The command line option always overrides  the  environment  vari‐
221       able.
222
223       The current known TCTIs are:
224
225       • 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
229       • mssim  - Typically used for communicating to the TPM software simula‐
230         tor.
231
232       • device - Used when talking directly to a TPM device file.
233
234       • 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
240       The arguments to either the command  line  option  or  the  environment
241       variable are in the form:
242
243       <tcti-name>:<tcti-option-config>
244
245       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
249   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
257   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

TCTI OPTIONS

264       This collection of options are used to configure the various known TCTI
265       modules available:
266
267device: 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
270         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
271         vice:/dev/tpm0”
272
273mssim: 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
277         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
278         TI=“mssim:host=localhost,port=2321”
279
280abrmd:  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
284         • TCTI abrmd supports two keys:
285
286           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
287              string).
288
289           2. `bus_type' : The type of the dbus instance (a string) limited to
290              `session' and `system'.
291
292         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
293         ample.FooBar:
294
295                \--tcti=tabrmd:bus_name=com.example.FooBar
296
297         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298         sion:
299
300                \--tcti:bus_type=session
301
302         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
303         ules.
304

EXAMPLES

306              echo "12345678" > secret.data
307
308              tpm2_createek -Q -c 0x81010001 -G rsa -u ek.pub
309
310              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
313              file_size=`stat --printf="%s" ak.name`
314              loaded_key_name=`cat ak.name | xxd -p -c $file_size`
315
316              tpm2_makecredential -Q -e ek.pub  -s secret.data -n $loaded_key_name \
317              -o mkcred.out
318
319              tpm2_startauthsession --policy-session -S session.ctx
320
321              tpm2_policysecret -S session.ctx -c e
322
323              tpm2_activatecredential -Q -c ak.ctx -C 0x81010001 -i mkcred.out \
324              -o actcred.out -p akpass -P"session:session.ctx"
325
326              tpm2_flushcontext session.ctx
327

Returns

329       Tools can return any of the following codes:
330
331       • 0 - Success.
332
333       • 1 - General non-specific error.
334
335       • 2 - Options handling error.
336
337       • 3 - Authentication error.
338
339       • 4 - TCTI related error.
340
341       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
342

BUGS

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

HELP

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