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

NAME

6       tpm2_certifycreation(1)  - Attest the association between a loaded pub‐
7       lic area and the provided hash of the creation data.
8

SYNOPSIS

10       tpm2_certifycreation [OPTIONS]
11

DESCRIPTION

13       tpm2_certifycreation(1) - Attest the association between a loaded  pub‐
14       lic area and the provided hash of the creation data.  The creation data
15       and the creation ticket is produced when creating the object.  The  ob‐
16       ject  itself  is  created with either TPM2_CreatePrimary or TPM2_Create
17       commands.
18

OPTIONS

20-C, --signingkey-context=OBJECT:
21
22         Context object pointing to the key used that signs the attestation.
23
24-P, --signingkey-auth_AUTH_:
25
26         Optional authorization value to use for the key specified by -C.
27
28-c, --certifiedkey-context=OBJECT:
29
30         Context object pointing to the key that has to be certified.
31
32-g, --hash-algorithm=ALGORITHM:
33
34         The hash algorithm used to digest the creation data.
35
36-s, --scheme=ALGORITHM:
37
38         The signing scheme used to sign the attestation data.
39
40-d, --creation-hash=FILE
41
42         File containing the digest of the creation data.
43
44-t, --ticket=FILE:
45
46         The ticket file to validate that the creation data  was  produced  by
47         the TPM.
48
49-o, --signature=FILE:
50
51         File  containing the signature of the attestation data for the certi‐
52         fied key.
53
54-f, --format=FORMAT:
55
56         Output signature format selection.
57
58–attestation=FILE:
59
60         The attestation data of the type TPM2_CREATION_INFO signed with sign‐
61         ing key.
62
63-q, --qualification=FILE_OR_HEX:
64
65         Optional, the policy qualifier data that the signer can choose to in‐
66         clude in the signature.  Can either be a path or hex string.
67
68--cphash=FILE
69
70         File path to record the hash of the command parameters.  This is com‐
71         monly termed as cpHash.  NOTE: When this option is selected, The tool
72         will not actually execute the command, it simply  returns  a  cpHash,
73         unless rphash is also required.
74
75--rphash=FILE
76
77         File  path  to  record  the hash of the response parameters.  This is
78         commonly termed as rpHash.
79
80-S, --session=FILE:
81
82         The session created using tpm2_startauthsession.  This can be used to
83         specify  an  auxiliary session for auditing and or encryption/decryp‐
84         tion of the parameters.
85
86   References

Context Object Format

88       The type of a context object, whether it is a handle or file  name,  is
89       determined according to the following logic in-order:
90
91       • If the argument is a file path, then the file is loaded as a restored
92         TPM transient object.
93
94       • If the argument is a prefix match on one of:
95
96         • owner: the owner hierarchy
97
98         • platform: the platform hierarchy
99
100         • endorsement: the endorsement hierarchy
101
102         • lockout: the lockout control persistent object
103
104       • If the argument argument can be loaded as a number it will  be  treat
105         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
106

Authorization Formatting

108       Authorization  for  use  of an object in TPM2.0 can come in 3 different
109       forms: 1.  Password 2.  HMAC 3.  Sessions
110
111       NOTE: “Authorizations default to the EMPTY  PASSWORD  when  not  speci‐
112       fied”.
113
114   Passwords
115       Passwords  are  interpreted  in  the following forms below using prefix
116       identifiers.
117
118       Note: By default passwords are assumed to be in the  string  form  when
119       they do not have a prefix.
120
121   String
122       A  string  password,  specified  by  prefix “str:” or it’s absence (raw
123       string without prefix) is not interpreted, and is directly used for au‐
124       thorization.
125
126   Examples
127              foobar
128              str:foobar
129
130   Hex-string
131       A  hex-string  password, specified by prefix “hex:” is converted from a
132       hexidecimal form into a byte array form, thus allowing  passwords  with
133       non-printable and/or terminal un-friendly characters.
134
135   Example
136              hex:0x1122334455667788
137
138   File
139       A  file  based password, specified be prefix “file:” should be the path
140       of a file containing the password to be read by the tool or  a  “-”  to
141       use  stdin.   Storing  passwords in files prevents information leakage,
142       passwords passed as options can be read from the process list or common
143       shell history features.
144
145   Examples
146              # to use stdin and be prompted
147              file:-
148
149              # to use a file from a path
150              file:path/to/password/file
151
152              # to echo a password via stdin:
153              echo foobar | tpm2_tool -p file:-
154
155              # to use a bash here-string via stdin:
156
157              tpm2_tool -p file:- <<< foobar
158
159   Sessions
160       When  using  a policy session to authorize the use of an object, prefix
161       the option argument with the session keyword.  Then indicate a path  to
162       a session file that was created with tpm2_startauthsession(1).  Option‐
163       ally, if the session requires an auth value to be sent with the session
164       handle  (eg policy password), then append a + and a string as described
165       in the Passwords section.
166
167   Examples
168       To use a session context file called session.ctx.
169
170              session:session.ctx
171
172       To use a session context file called session.ctx AND send the authvalue
173       mypassword.
174
175              session:session.ctx+mypassword
176
177       To use a session context file called session.ctx AND send the HEX auth‐
178       value 0x11223344.
179
180              session:session.ctx+hex:11223344
181
182   PCR Authorizations
183       You can satisfy a PCR policy using the “pcr:” prefix and the PCR  mini‐
184       language.       The     PCR     minilanguage     is     as     follows:
185       <pcr-spec>=<raw-pcr-file>
186
187       The PCR spec is documented in in the section “PCR bank specifiers”.
188
189       The raw-pcr-file is an optional argument that contains  the  output  of
190       the raw PCR contents as returned by tpm2_pcrread(1).
191
192       PCR bank specifiers (pcr.md)
193
194   Examples
195       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
196       er of:
197
198              pcr:sha256:0,1,2,3
199
200       specifying AUTH.
201

Algorithm Specifiers

203       Options that take algorithms support “nice-names”.
204
205       There are two major algorithm specification string classes, simple  and
206       complex.  Only certain algorithms will be accepted by the TPM, based on
207       usage and conditions.
208
209   Simple specifiers
210       These are strings with no additional specification data.  When creating
211       objects,  non-specified  portions of an object are assumed to defaults.
212       You can find the list of known “Simple Specifiers Below”.
213
214   Asymmetric
215       • rsa
216
217       • ecc
218
219   Symmetric
220       • aes
221
222       • camellia
223
224   Hashing Algorithms
225       • sha1
226
227       • sha256
228
229       • sha384
230
231       • sha512
232
233       • sm3_256
234
235       • sha3_256
236
237       • sha3_384
238
239       • sha3_512
240
241   Keyed Hash
242       • hmac
243
244       • xor
245
246   Signing Schemes
247       • rsassa
248
249       • rsapss
250
251       • ecdsa
252
253       • ecdaa
254
255       • ecschnorr
256
257   Asymmetric Encryption Schemes
258       • oaep
259
260       • rsaes
261
262       • ecdh
263
264   Modes
265       • ctr
266
267       • ofb
268
269       • cbc
270
271       • cfb
272
273       • ecb
274
275   Misc
276       • null
277
278   Complex Specifiers
279       Objects, when specified for creation by the TPM,  have  numerous  algo‐
280       rithms  to  populate  in the public data.  Things like type, scheme and
281       asymmetric details, key size, etc.  Below is  the  general  format  for
282       specifying this data: <type>:<scheme>:<symmetric-details>
283
284   Type Specifiers
285       This  portion  of the complex algorithm specifier is required.  The re‐
286       maining scheme and symmetric details will default  based  on  the  type
287       specified and the type of the object being created.
288
289       • aes - Default AES: aes128
290
291       • aes128<mode>  - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
292         If mode is not specified, defaults to null.
293
294       • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
295
296       • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
297
298       • ecc - Elliptical Curve, defaults to ecc256.
299
300       • ecc192 - 192 bit ECC
301
302       • ecc224 - 224 bit ECC
303
304       • ecc256 - 256 bit ECC
305
306       • ecc384 - 384 bit ECC
307
308       • ecc521 - 521 bit ECC
309
310       • rsa - Default RSA: rsa2048
311
312       • rsa1024 - RSA with 1024 bit keysize.
313
314       • rsa2048 - RSA with 2048 bit keysize.
315
316       • rsa4096 - RSA with 4096 bit keysize.
317
318   Scheme Specifiers
319       Next, is an optional field, it can be skipped.
320
321       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
322       Most signing schemes take a hash algorithm directly following the sign‐
323       ing scheme.  If the hash algorithm is missing, it defaults  to  sha256.
324       Some take no arguments, and some take multiple arguments.
325
326   Hash Optional Scheme Specifiers
327       These  scheme  specifiers are followed by a dash and a valid hash algo‐
328       rithm, For example: oaep-sha256.
329
330       • oaep
331
332       • ecdh
333
334       • rsassa
335
336       • rsapss
337
338       • ecdsa
339
340       • ecschnorr
341
342   Multiple Option Scheme Specifiers
343       This scheme specifier is followed by a count  (max  size  UINT16)  then
344       followed by a dash(-) and a valid hash algorithm.  * ecdaa For example,
345       ecdaa4-sha256.  If no count is specified, it defaults to 4.
346
347   No Option Scheme Specifiers
348       This scheme specifier takes NO arguments.  * rsaes
349
350   Symmetric Details Specifiers
351       This field is optional, and defaults based on the type of object  being
352       created  and it’s attributes.  Generally, any valid Symmetric specifier
353       from the Type Specifiers list should work.  If not specified, an  asym‐
354       metric objects symmetric details defaults to aes128cfb.
355
356   Examples
357   Create an rsa2048 key with an rsaes asymmetric encryption scheme
358       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
359
360   Create  an  ecc256  key  with an ecdaa signing scheme with a count of 4 and
361       sha384 hash
362       /tpm2_create  -C  parent.ctx  -G  ecc256:ecdaa4-sha384  -u  key.pub  -r
363       key.priv cryptographic algorithms ALGORITHM.
364

COMMON OPTIONS

366       This  collection of options are common to many programs and provide in‐
367       formation that many users may expect.
368
369-h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
370         attempts  to  invoke  the  manpager for the tool, however, on failure
371         will output a short tool summary.  This is the same behavior  if  the
372         “man”  option argument is specified, however if explicit “man” is re‐
373         quested, the tool will provide errors from man  on  stderr.   If  the
374         “no-man”  option  if  specified, or the manpager fails, the short op‐
375         tions will be output to stdout.
376
377         To successfully use the manpages feature requires the manpages to  be
378         installed or on MANPATH, See man(1) for more details.
379
380-v,  --version:  Display version information for this tool, supported
381         tctis and exit.
382
383-V, --verbose: Increase the information that the tool prints  to  the
384         console  during  its  execution.  When using this option the file and
385         line number are printed.
386
387-Q, --quiet: Silence normal tool output to stdout.
388
389-Z, --enable-errata: Enable the application of errata fixups.  Useful
390         if  an  errata fixup needs to be applied to commands sent to the TPM.
391         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
392         formation many users may expect.
393

TCTI Configuration

395       The  TCTI  or  “Transmission  Interface” is the communication mechanism
396       with the TPM.  TCTIs can be changed for communication with TPMs  across
397       different mediums.
398
399       To control the TCTI, the tools respect:
400
401       1. The command line option -T or --tcti
402
403       2. The environment variable: TPM2TOOLS_TCTI.
404
405       Note:  The  command  line option always overrides the environment vari‐
406       able.
407
408       The current known TCTIs are:
409
410       • tabrmd     -     The     resource     manager,     called      tabrmd
411         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
412         abrmd as a tcti name are synonymous.
413
414       • mssim - Typically used for communicating to the TPM software  simula‐
415         tor.
416
417       • device - Used when talking directly to a TPM device file.
418
419       • none  - Do not initalize a connection with the TPM.  Some tools allow
420         for off-tpm options and thus support not using a TCTI.  Tools that do
421         not  support  it  will error when attempted to be used without a TCTI
422         connection.  Does not support ANY options and MUST  BE  presented  as
423         the exact text of “none”.
424
425       The  arguments  to  either  the  command line option or the environment
426       variable are in the form:
427
428       <tcti-name>:<tcti-option-config>
429
430       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
431       tion-config> results in the default being used for that portion respec‐
432       tively.
433
434   TCTI Defaults
435       When a TCTI is not specified, the default TCTI is  searched  for  using
436       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
437       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
438       what TCTI will be chosen as the default by using the -v option to print
439       the version information.  The “default-tcti” key-value pair will  indi‐
440       cate which of the aforementioned TCTIs is the default.
441
442   Custom TCTIs
443       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
444       tools internally use dlopen(3), and the raw tcti-name value is used for
445       the lookup.  Thus, this could be a path to the shared library, or a li‐
446       brary name as understood by dlopen(3) semantics.
447

TCTI OPTIONS

449       This collection of options are used to configure the various known TCTI
450       modules available:
451
452device: For the device TCTI, the TPM character device file for use by
453         the device TCTI can be specified.  The default is /dev/tpm0.
454
455         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI=“de‐
456         vice:/dev/tpm0”
457
458mssim:  For  the  mssim  TCTI, the domain name or IP address and port
459         number used by the simulator  can  be  specified.   The  default  are
460         127.0.0.1 and 2321.
461
462         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
463         TI=“mssim:host=localhost,port=2321”
464
465abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
466         ries  of  simple  key value pairs separated by a `,' character.  Each
467         key and value string are separated by a `=' character.
468
469         • TCTI abrmd supports two keys:
470
471           1. `bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
472              string).
473
474           2. `bus_type' : The type of the dbus instance (a string) limited to
475              `session' and `system'.
476
477         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
478         ample.FooBar:
479
480                \--tcti=tabrmd:bus_name=com.example.FooBar
481
482         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
483         sion:
484
485                \--tcti:bus_type=session
486
487         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
488         ules.  # Signature Format Specifiers
489
490       Format selection for the signature output file.  tss (the default) will
491       output a binary blob according to the TPM 2.0 specification and any po‐
492       tential  compiler padding.  The option plain will output the plain sig‐
493       nature data as defined by the used cryptographic algorithm.
494

EXAMPLES

496   Certify creation data of a primary key.
497              tpm2_createprimary -C o -c prim.ctx --creation-data create.dat \
498              -d create.dig -t create.ticket
499
500              tpm2_create -G rsa -u rsa.pub -r rsa.priv -C prim.ctx -c signing_key.ctx
501
502              tpm2_certifycreation -C signing_key.ctx -c prim.ctx -d create.dig \
503              -t create.ticket -g sha256 -o sig.nature --attestation attestat.ion -f plain \
504              -s rsassa
505

Returns

507       Tools can return any of the following codes:
508
509       • 0 - Success.
510
511       • 1 - General non-specific error.
512
513       • 2 - Options handling error.
514
515       • 3 - Authentication error.
516
517       • 4 - TCTI related error.
518
519       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
520

BUGS

522       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
523

HELP

525       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
526
527
528
529tpm2-tools                                             tpm2_certifycreation(1)
Impressum