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

NAME

6       tpm2_certify(1) - Prove that an object is loaded in the TPM.
7

SYNOPSIS

9       tpm2_certify [OPTIONS]
10

DESCRIPTION

12       tpm2_certify(1)  - Proves that an object with a specific NAME is loaded
13       in the TPM.  By certifying that the object is loaded, the TPM  warrants
14       that  a public area with a given NAME is self-consistent and associated
15       with a valid sensitive area.
16
17       If a relying party has a public area that has the same NAME as  a  NAME
18       certified  with  this  command, then the values in that public area are
19       correct.  An object that only has its public area loaded cannot be cer‐
20       tified.
21

OPTIONS

23       These options control the certification:
24
25-c, --certifiedkey-context=OBJECT:
26
27         The object to be certified.
28
29-C, --signingkey-context=OBJECT:
30
31         The key used to sign the attestation structure.
32
33-p, --certifiedkey-auth=AUTH:
34
35         The authorization value provided for the object specified with -c.
36
37-g, --hash-algorithm=ALGORITHM:
38
39         The hash algorithm to use in signature generation.
40
41-P, --signingkey-auth=AUTH:
42
43         The authorization value for the signing key specified with -C.
44
45-o, --attestation=FILE:
46
47         Output file name for the attestation data.
48
49-s, --signature=FILE:
50
51         Output file name for the signature data.
52
53-f, --format=FORMAT:
54
55         Format selection for the signature output file.
56
57--cphash=FILE
58
59         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         unless rphash is also required.
63
64--rphash=FILE
65
66         File path to record the hash of the  response  parameters.   This  is
67         commonly termed as rpHash.
68
69-S, --session=FILE:
70
71         The session created using tpm2_startauthsession.  This can be used to
72         specify an auxiliary session for auditing and  or  encryption/decryp‐
73         tion of the parameters.
74
75   References

Context Object Format

77       The  type  of a context object, whether it is a handle or file name, is
78       determined according to the following logic in-order:
79
80       • If the argument is a file path, then the file is loaded as a restored
81         TPM transient object.
82
83       • If the argument is a prefix match on one of:
84
85         • owner: the owner hierarchy
86
87         • platform: the platform hierarchy
88
89         • endorsement: the endorsement hierarchy
90
91         • lockout: the lockout control persistent object
92
93       • If  the  argument argument can be loaded as a number it will be treat
94         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
95

Authorization Formatting

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

Algorithm Specifiers

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

Signature Format Specifiers

355       Format selection for the signature output file.  tss (the default) will
356       output a binary blob according to the TPM 2.0 specification and any po‐
357       tential compiler padding.  The option plain will output the plain  sig‐
358       nature  data as defined by the used cryptographic algorithm.  signature
359       FORMAT.
360

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

445       This collection of options are used to configure the various known TCTI
446       modules available:
447
448device: For the device TCTI, the TPM character device file for use by
449         the device TCTI can be specified.  The default is /dev/tpm0.
450
451         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
452         vice:/dev/tpm0”
453
454mssim: For the mssim TCTI, the domain name or  IP  address  and  port
455         number  used  by  the  simulator  can  be specified.  The default are
456         127.0.0.1 and 2321.
457
458         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
459         TI=“mssim:host=localhost,port=2321”
460
461abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
462         ries of simple key value pairs separated by a  `,'  character.   Each
463         key and value string are separated by a `=' character.
464
465         • TCTI abrmd supports two keys:
466
467           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
468              string).
469
470           2. `bus_type' : The type of the dbus instance (a string) limited to
471              `session' and `system'.
472
473         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
474         ample.FooBar:
475
476                \--tcti=tabrmd:bus_name=com.example.FooBar
477
478         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
479         sion:
480
481                \--tcti:bus_type=session
482
483         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
484         ules.
485

EXAMPLES

487       Create a primary key and certify it with a signing key.
488
489              tpm2_createprimary -Q -C e -g sha256 -G rsa -c primary.ctx
490
491              tpm2_create -Q -g sha256 -G rsa -u certify.pub -r certify.priv -C primary.ctx
492
493              tpm2_load -Q -C primary.ctx -u certify.pub -r certify.priv -n certify.name \
494              -c certify.ctx
495
496              tpm2_certify -Q -c primary.ctx -C certify.ctx -g sha256 -o attest.out -s sig.out
497

Returns

499       Tools can return any of the following codes:
500
501       • 0 - Success.
502
503       • 1 - General non-specific error.
504
505       • 2 - Options handling error.
506
507       • 3 - Authentication error.
508
509       • 4 - TCTI related error.
510
511       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
512

BUGS

514       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
515

HELP

517       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
518
519
520
521tpm2-tools                                                     tpm2_certify(1)
Impressum