1tpm2_certify(1) General Commands Manual tpm2_certify(1)
2
3
4
6 tpm2_certify(1) - Prove that an object is loaded in the TPM.
7
9 tpm2_certify [OPTIONS]
10
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
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 • --scheme=ALGORITHM:
42
43 The signing scheme used to sign the message. Optional. Signing
44 schemes should follow the “formatting standards”, see section “Algo‐
45 rithm Specifiers”. Also, see section “Supported Signing Schemes” for
46 a list of supported signature schemes. If specified, the signature
47 scheme must match the key type. If left unspecified, a default sig‐
48 nature scheme for the key type will be used.
49
50 • -p, --signingkey-auth=AUTH:
51
52 The authorization value for the signing key specified with -C.
53
54 • -o, --attestation=FILE:
55
56 Output file name for the attestation data.
57
58 • -s, --signature=FILE:
59
60 Output file name for the signature data.
61
62 • -f, --format=FORMAT:
63
64 Format selection for the signature output file.
65
66 • --cphash=FILE
67
68 File path to record the hash of the command parameters. This is com‐
69 monly termed as cpHash. NOTE: When this option is selected, The tool
70 will not actually execute the command, it simply returns a cpHash,
71 unless rphash is also required.
72
73 • --rphash=FILE
74
75 File path to record the hash of the response parameters. This is
76 commonly termed as rpHash.
77
78 • -S, --session=FILE:
79
80 The session created using tpm2_startauthsession. This can be used to
81 specify an auxiliary session for auditing and or encryption/decryp‐
82 tion of the parameters.
83
84 References
86 The type of a context object, whether it is a handle or file name, is
87 determined according to the following logic in-order:
88
89 • If the argument is a file path, then the file is loaded as a restored
90 TPM transient object.
91
92 • If the argument is a prefix match on one of:
93
94 • owner: the owner hierarchy
95
96 • platform: the platform hierarchy
97
98 • endorsement: the endorsement hierarchy
99
100 • lockout: the lockout control persistent object
101
102 • If the argument argument can be loaded as a number it will be treat
103 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
104
106 Authorization for use of an object in TPM2.0 can come in 3 different
107 forms: 1. Password 2. HMAC 3. Sessions
108
109 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
110 fied”.
111
112 Passwords
113 Passwords are interpreted in the following forms below using prefix
114 identifiers.
115
116 Note: By default passwords are assumed to be in the string form when
117 they do not have a prefix.
118
119 String
120 A string password, specified by prefix “str:” or it’s absence (raw
121 string without prefix) is not interpreted, and is directly used for au‐
122 thorization.
123
124 Examples
125 foobar
126 str:foobar
127
128 Hex-string
129 A hex-string password, specified by prefix “hex:” is converted from a
130 hexidecimal form into a byte array form, thus allowing passwords with
131 non-printable and/or terminal un-friendly characters.
132
133 Example
134 hex:1122334455667788
135
136 File
137 A file based password, specified be prefix “file:” should be the path
138 of a file containing the password to be read by the tool or a “-” to
139 use stdin. Storing passwords in files prevents information leakage,
140 passwords passed as options can be read from the process list or common
141 shell history features.
142
143 Examples
144 # to use stdin and be prompted
145 file:-
146
147 # to use a file from a path
148 file:path/to/password/file
149
150 # to echo a password via stdin:
151 echo foobar | tpm2_tool -p file:-
152
153 # to use a bash here-string via stdin:
154
155 tpm2_tool -p file:- <<< foobar
156
157 Sessions
158 When using a policy session to authorize the use of an object, prefix
159 the option argument with the session keyword. Then indicate a path to
160 a session file that was created with tpm2_startauthsession(1). Option‐
161 ally, if the session requires an auth value to be sent with the session
162 handle (eg policy password), then append a + and a string as described
163 in the Passwords section.
164
165 Examples
166 To use a session context file called session.ctx.
167
168 session:session.ctx
169
170 To use a session context file called session.ctx AND send the authvalue
171 mypassword.
172
173 session:session.ctx+mypassword
174
175 To use a session context file called session.ctx AND send the HEX auth‐
176 value 0x11223344.
177
178 session:session.ctx+hex:11223344
179
180 PCR Authorizations
181 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
182 language. The PCR minilanguage is as follows:
183 <pcr-spec>=<raw-pcr-file>
184
185 The PCR spec is documented in in the section “PCR bank specifiers”.
186
187 The raw-pcr-file is an optional argument that contains the output of
188 the raw PCR contents as returned by tpm2_pcrread(1).
189
190 PCR bank specifiers (pcr.md)
191
192 Examples
193 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
194 er of:
195
196 pcr:sha256:0,1,2,3
197
198 specifying AUTH.
199
201 Options that take algorithms support “nice-names”.
202
203 There are two major algorithm specification string classes, simple and
204 complex. Only certain algorithms will be accepted by the TPM, based on
205 usage and conditions.
206
207 Simple specifiers
208 These are strings with no additional specification data. When creating
209 objects, non-specified portions of an object are assumed to defaults.
210 You can find the list of known “Simple Specifiers” below.
211
212 Asymmetric
213 • rsa
214
215 • ecc
216
217 Symmetric
218 • aes
219
220 • camellia
221
222 • sm4
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 • sm2
258
259 Asymmetric Encryption Schemes
260 • oaep
261
262 • rsaes
263
264 • ecdh
265
266 Modes
267 • ctr
268
269 • ofb
270
271 • cbc
272
273 • cfb
274
275 • ecb
276
277 Misc
278 • null
279
280 Complex Specifiers
281 Objects, when specified for creation by the TPM, have numerous algo‐
282 rithms to populate in the public data. Things like type, scheme and
283 asymmetric details, key size, etc. Below is the general format for
284 specifying this data: <type>:<scheme>:<symmetric-details>
285
286 Type Specifiers
287 This portion of the complex algorithm specifier is required. The re‐
288 maining scheme and symmetric details will default based on the type
289 specified and the type of the object being created.
290
291 • aes - Default AES: aes128
292
293 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
294 If mode is not specified, defaults to null.
295
296 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
297
298 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
299
300 • sm4 - Default SM4: sm4128
301
302 • sm4128 or sm4_128 <mode> - 128 bit SM4 with optional mode
303 (ctr|ofb|cbc|cfb|ecb). If mode is not specified, defaults to null.
304
305 • ecc - Elliptical Curve, defaults to ecc256.
306
307 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
308
309 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
310
311 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
312
313 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
314
315 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
316
317 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
318
319 • rsa - Default RSA: rsa2048
320
321 • rsa1024 - RSA with 1024 bit keysize.
322
323 • rsa2048 - RSA with 2048 bit keysize.
324
325 • rsa3072 - RSA with 3072 bit keysize.
326
327 • rsa4096 - RSA with 4096 bit keysize.
328
329 Scheme Specifiers
330 Next, is an optional field, it can be skipped.
331
332 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
333 Most signing schemes take a hash algorithm directly following the sign‐
334 ing scheme. If the hash algorithm is missing, it defaults to sha256.
335 Some take no arguments, and some take multiple arguments.
336
337 Hash Optional Scheme Specifiers
338 These scheme specifiers are followed by a dash and a valid hash algo‐
339 rithm, For example: oaep-sha256.
340
341 • oaep
342
343 • ecdh
344
345 • rsassa
346
347 • rsapss
348
349 • ecdsa
350
351 • ecschnorr
352
353 • sm2
354
355 Multiple Option Scheme Specifiers
356 This scheme specifier is followed by a count (max size UINT16) then
357 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
358 ecdaa4-sha256. If no count is specified, it defaults to 4.
359
360 No Option Scheme Specifiers
361 This scheme specifier takes NO arguments. * rsaes
362
363 Symmetric Details Specifiers
364 This field is optional, and defaults based on the type of object being
365 created and it’s attributes. Generally, any valid Symmetric specifier
366 from the Type Specifiers list should work. If not specified, an asym‐
367 metric objects symmetric details defaults to aes128cfb.
368
369 Examples
370 Create an rsa2048 key with an rsaes asymmetric encryption scheme
371 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
372
373 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
374 sha384 hash
375 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
376 key.priv cryptographic algorithms ALGORITHM.
377
379 Format selection for the signature output file. tss (the default) will
380 output a binary blob according to the TPM 2.0 specification and any po‐
381 tential compiler padding. The option plain will output the plain sig‐
382 nature data as defined by the used cryptographic algorithm. signature
383 FORMAT.
384
386 This collection of options are common to many programs and provide in‐
387 formation that many users may expect.
388
389 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
390 attempts to invoke the manpager for the tool, however, on failure
391 will output a short tool summary. This is the same behavior if the
392 “man” option argument is specified, however if explicit “man” is re‐
393 quested, the tool will provide errors from man on stderr. If the
394 “no-man” option if specified, or the manpager fails, the short op‐
395 tions will be output to stdout.
396
397 To successfully use the manpages feature requires the manpages to be
398 installed or on MANPATH, See man(1) for more details.
399
400 • -v, --version: Display version information for this tool, supported
401 tctis and exit.
402
403 • -V, --verbose: Increase the information that the tool prints to the
404 console during its execution. When using this option the file and
405 line number are printed.
406
407 • -Q, --quiet: Silence normal tool output to stdout.
408
409 • -Z, --enable-errata: Enable the application of errata fixups. Useful
410 if an errata fixup needs to be applied to commands sent to the TPM.
411 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
412 formation many users may expect.
413
415 The TCTI or “Transmission Interface” is the communication mechanism
416 with the TPM. TCTIs can be changed for communication with TPMs across
417 different mediums.
418
419 To control the TCTI, the tools respect:
420
421 1. The command line option -T or --tcti
422
423 2. The environment variable: TPM2TOOLS_TCTI.
424
425 Note: The command line option always overrides the environment vari‐
426 able.
427
428 The current known TCTIs are:
429
430 • tabrmd - The resource manager, called tabrmd
431 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
432 abrmd as a tcti name are synonymous.
433
434 • mssim - Typically used for communicating to the TPM software simula‐
435 tor.
436
437 • device - Used when talking directly to a TPM device file.
438
439 • none - Do not initalize a connection with the TPM. Some tools allow
440 for off-tpm options and thus support not using a TCTI. Tools that do
441 not support it will error when attempted to be used without a TCTI
442 connection. Does not support ANY options and MUST BE presented as
443 the exact text of “none”.
444
445 The arguments to either the command line option or the environment
446 variable are in the form:
447
448 <tcti-name>:<tcti-option-config>
449
450 Specifying an empty string for either the <tcti-name> or <tcti-op‐
451 tion-config> results in the default being used for that portion respec‐
452 tively.
453
454 TCTI Defaults
455 When a TCTI is not specified, the default TCTI is searched for using
456 dlopen(3) semantics. The tools will search for tabrmd, device and
457 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
458 what TCTI will be chosen as the default by using the -v option to print
459 the version information. The “default-tcti” key-value pair will indi‐
460 cate which of the aforementioned TCTIs is the default.
461
462 Custom TCTIs
463 Any TCTI that implements the dynamic TCTI interface can be loaded. The
464 tools internally use dlopen(3), and the raw tcti-name value is used for
465 the lookup. Thus, this could be a path to the shared library, or a li‐
466 brary name as understood by dlopen(3) semantics.
467
469 This collection of options are used to configure the various known TCTI
470 modules available:
471
472 • device: For the device TCTI, the TPM character device file for use by
473 the device TCTI can be specified. The default is /dev/tpm0.
474
475 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
476 vice:/dev/tpm0”
477
478 • mssim: For the mssim TCTI, the domain name or IP address and port
479 number used by the simulator can be specified. The default are
480 127.0.0.1 and 2321.
481
482 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
483 TI=“mssim:host=localhost,port=2321”
484
485 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
486 ries of simple key value pairs separated by a `,' character. Each
487 key and value string are separated by a `=' character.
488
489 • TCTI abrmd supports two keys:
490
491 1. `bus_name' : The name of the tabrmd service on the bus (a
492 string).
493
494 2. `bus_type' : The type of the dbus instance (a string) limited to
495 `session' and `system'.
496
497 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
498 ample.FooBar:
499
500 \--tcti=tabrmd:bus_name=com.example.FooBar
501
502 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
503 sion:
504
505 \--tcti:bus_type=session
506
507 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
508 ules.
509
511 Create a primary key and certify it with a signing key.
512
513 tpm2_createprimary -Q -C e -g sha256 -G rsa -c primary.ctx
514
515 tpm2_create -Q -g sha256 -G rsa -u certify.pub -r certify.priv -C primary.ctx
516
517 tpm2_load -Q -C primary.ctx -u certify.pub -r certify.priv -n certify.name \
518 -c certify.ctx
519
520 tpm2_certify -Q -c primary.ctx -C certify.ctx -g sha256 -o attest.out -s sig.out
521
523 Tools can return any of the following codes:
524
525 • 0 - Success.
526
527 • 1 - General non-specific error.
528
529 • 2 - Options handling error.
530
531 • 3 - Authentication error.
532
533 • 4 - TCTI related error.
534
535 • 5 - Non supported scheme. Applicable to tpm2_testparams.
536
538 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
539
541 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
542 fo/tpm2)
543
544
545
546tpm2-tools tpm2_certify(1)