1tpm2_certify(1) General Commands Manual tpm2_certify(1)
2
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 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 • -c, --certifiedkey-context=OBJECT:
26 The object to be certified.
28 • -C, --signingkey-context=OBJECT:
30 The key used to sign the attestation structure.
32 • -P, --certifiedkey-auth=AUTH:
34 The authorization value provided for the object specified with -c.
36 • -g, --hash-algorithm=ALGORITHM:
38 The hash algorithm to use in signature generation.
40 • --scheme=ALGORITHM:
42 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 • -p, --signingkey-auth=AUTH:
51 The authorization value for the signing key specified with -C.
53 • -o, --attestation=FILE:
55 Output file name for the attestation data.
57 • -s, --signature=FILE:
59 Output file name for the signature data.
61 • -f, --format=FORMAT:
63 Format selection for the signature output file.
65 • --cphash=FILE
67 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 • --rphash=FILE
74 File path to record the hash of the response parameters. This is
76 commonly termed as rpHash.
77 • -S, --session=FILE:
79 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 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 • If the argument is a file path, then the file is loaded as a restored
90 TPM transient object.
91 • If the argument is a prefix match on one of:
93 • owner: the owner hierarchy
95 • platform: the platform hierarchy
97 • endorsement: the endorsement hierarchy
99 • lockout: the lockout control persistent object
101 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
110 fied”.
111 Passwords
113 Passwords are interpreted in the following forms below using prefix
114 identifiers.
115 Note: By default passwords are assumed to be in the string form when
117 they do not have a prefix.
118 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 Examples
125 foobar
126 str:foobar
127 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 Example
134 hex:1122334455667788
135 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 Examples
144 # to use stdin and be prompted
145 file:-
146 # to use a file from a path
148 file:path/to/password/file
149 # to echo a password via stdin:
151 echo foobar | tpm2_tool -p file:-
152 # to use a bash here-string via stdin:
154 tpm2_tool -p file:- <<< foobar
156 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 Examples
166 To use a session context file called session.ctx.
167 session:session.ctx
169 To use a session context file called session.ctx AND send the authvalue
171 mypassword.
172 session:session.ctx+mypassword
174 To use a session context file called session.ctx AND send the HEX auth‐
176 value 0x11223344.
177 session:session.ctx+hex:11223344
179 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 The PCR spec is documented in in the section “PCR bank specifiers”.
186 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 PCR bank specifiers (pcr.md)
191 Examples
193 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
194 er of:
195 pcr:sha256:0,1,2,3
197 specifying AUTH.
199
201 Options that take algorithms support “nice-names”.
202 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 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 Asymmetric
213 • rsa
214 • ecc
216 Symmetric
218 • aes
219 • camellia
221 • sm4
223 Hashing Algorithms
225 • sha1
226 • sha256
228 • sha384
230 • sha512
232 • sm3_256
234 • sha3_256
236 • sha3_384
238 • sha3_512
240 Keyed Hash
242 • hmac
243 • xor
245 Signing Schemes
247 • rsassa
248 • rsapss
250 • ecdsa
252 • ecdaa
254 • ecschnorr
256 • sm2
258 Asymmetric Encryption Schemes
260 • oaep
261 • rsaes
263 • ecdh
265 Modes
267 • ctr
268 • ofb
270 • cbc
272 • cfb
274 • ecb
276 Misc
278 • null
279 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 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 • aes - Default AES: aes128
292 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
294 If mode is not specified, defaults to null.
295 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
297 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
299 • sm4 - Default SM4: sm4128
301 • 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 • ecc - Elliptical Curve, defaults to ecc256.
306 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
308 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
310 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
312 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
314 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
316 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
318 • rsa - Default RSA: rsa2048
320 • rsa1024 - RSA with 1024 bit keysize.
322 • rsa2048 - RSA with 2048 bit keysize.
324 • rsa3072 - RSA with 3072 bit keysize.
326 • rsa4096 - RSA with 4096 bit keysize.
328 Scheme Specifiers
330 Next, is an optional field, it can be skipped.
331 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 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 • oaep
342 • ecdh
344 • rsassa
346 • rsapss
348 • ecdsa
350 • ecschnorr
352 • sm2
354 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 No Option Scheme Specifiers
361 This scheme specifier takes NO arguments. * rsaes
362 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 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 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 • -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 To successfully use the manpages feature requires the manpages to be
398 installed or on MANPATH, See man(1) for more details.
399 • -v, --version: Display version information for this tool, supported
401 tctis and exit.
402 • -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 • -Q, --quiet: Silence normal tool output to stdout.
408 • -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 To control the TCTI, the tools respect:
420 1. The command line option -T or --tcti
422 2. The environment variable: TPM2TOOLS_TCTI.
424 Note: The command line option always overrides the environment vari‐
426 able.
427 The current known TCTIs are:
429 • 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 • mssim - Typically used for communicating to the TPM software simula‐
435 tor.
436 • device - Used when talking directly to a TPM device file.
438 • 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 The arguments to either the command line option or the environment
446 variable are in the form:
447 <tcti-name>:<tcti-option-config>
449 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
476 vice:/dev/tpm0”
477 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
483 TI=“mssim:host=localhost,port=2321”
484 • 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 • TCTI abrmd supports two keys:
490 1. `bus_name' : The name of the tabrmd service on the bus (a
492 string).
493 2. `bus_type' : The type of the dbus instance (a string) limited to
495 `session' and `system'.
496 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
498 ample.FooBar:
499 \--tcti=tabrmd:bus_name=com.example.FooBar
501 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
503 sion:
504 \--tcti:bus_type=session
506 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 tpm2_createprimary -Q -C e -g sha256 -G rsa -c primary.ctx
514 tpm2_create -Q -g sha256 -G rsa -u certify.pub -r certify.priv -C primary.ctx
516 tpm2_load -Q -C primary.ctx -u certify.pub -r certify.priv -n certify.name \
518 -c certify.ctx
519 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 • 0 - Success.
526 • 1 - General non-specific error.
528 • 2 - Options handling error.
530 • 3 - Authentication error.
532 • 4 - TCTI related error.
534 • 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)
543tpm2-tools tpm2_certify(1)