1tpm2_createak(1) General Commands Manual tpm2_createak(1)
2
6 tpm2_createak(1) - Generate attestation key with given algorithm under
7 the endorsement hierarchy.
8
10 tpm2_createak [OPTIONS]
11
13 tpm2_createak(1) - Generate an attestation key (AK) with the given al‐
14 gorithm under the endorsement hierarchy. The context of the attesta‐
15 tion key is specified via -c.
16 The tool outputs to stdout a YAML representation of the loaded key’s
18 name, for example:
19 loaded-key:
21 name: 000bac149518baa05540a0678bd9b624f8a98d042e46c60f4d098ba394d36fc49268
22
24 • -P, --eh-auth=AUTH:
25 The authorization value for the endorsement hierarchy.
27 • -p, --ak-auth=AUTH
29 The authorization value for the attestation key object created.
31 • -C, --ek-context=OBJECT:
33 The endorsement key object.
35 • -c, --ak-context=FILE:
37 The file path to save the object context of the attestation key.
39 • -G, --key-algorithm=ALGORITHM:
41 Specifies the attestation key algorithm. Supports:
42 • ecc - An P256 key.
44 • rsa - An RSA2048 key.
46 • keyedhash - hmac key.
48 • -g, --hash-algorithm=ALGORITHM:
50 Specifies the digest algorithm used for signing.
52 • -s, --signing-algorithm=ALGORITHM:
54 The signing algorithm.
56 • -u, --public=FILE:
58 The file to save the public portion of the attestation key.
60 • -n, --ak-name=FILE:
62 The file to save the attestation key name, optional.
64 • -r, --private=FILE:
66 The output file which contains the sensitive portion of the object,
68 optional. # Protection Details
69 Objects that can move outside of TPM need to be protected (confiden‐
71 tiality and integrity). For instance, transient objects require that
72 TPM protected data (key or seal material) be stored outside of the TPM.
73 This is seen in tools like tpm2_create(1), where the -r option outputs
74 this protected data. This blob contains the sensitive portions of the
75 object. The sensitive portions of the object are protected by the par‐
76 ent object, using the parent’s symmetric encryption details to encrypt
77 the sensitive data and HMAC it.
78 In-depth details can be found in sections 23 of:
80 • https://trustedcomputinggroup.org/wp-content/up‐
82 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
83 Notably Figure 20, is relevant, even though it’s specifically referring
85 to duplication blobs, the process is identical.
86 If the output is from tpm2_duplicate(1), the output will be slightly
88 different, as described fully in section 23.
89 • -f, --format:
91 Format selection for the public key output file. `tss' (the default)
93 will output a binary blob according to the TPM 2.0 Specification.
94 `pem' will output an OpenSSL compatible PEM encoded public key.
95 `der' will output an OpenSSL compatible DER encoded public key.
96 `tpmt' will output a binary blob of the TPMT_PUBLIC struct referenced
97 by TPM 2.0 specs.
98 Format selection for the signature output file.
100 • -q, --ak-qualified-name=FILE:
102 The qualified name of the attestation key object. The qualified name
104 is the qualified name of the parent object (the EK in this instance)
105 and the name of the object itself. Thus, the qualified name of an
106 object serves to bind it to its parents.
107 References
110 The type of a context object, whether it is a handle or file name, is
111 determined according to the following logic in-order:
112 • If the argument is a file path, then the file is loaded as a restored
114 TPM transient object.
115 • If the argument is a prefix match on one of:
117 • owner: the owner hierarchy
119 • platform: the platform hierarchy
121 • endorsement: the endorsement hierarchy
123 • lockout: the lockout control persistent object
125 • If the argument argument can be loaded as a number it will be treat
127 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
128
130 Authorization for use of an object in TPM2.0 can come in 3 different
131 forms: 1. Password 2. HMAC 3. Sessions
132 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
134 fied”.
135 Passwords
137 Passwords are interpreted in the following forms below using prefix
138 identifiers.
139 Note: By default passwords are assumed to be in the string form when
141 they do not have a prefix.
142 String
144 A string password, specified by prefix “str:” or it’s absence (raw
145 string without prefix) is not interpreted, and is directly used for au‐
146 thorization.
147 Examples
149 foobar
150 str:foobar
151 Hex-string
153 A hex-string password, specified by prefix “hex:” is converted from a
154 hexidecimal form into a byte array form, thus allowing passwords with
155 non-printable and/or terminal un-friendly characters.
156 Example
158 hex:0x1122334455667788
159 File
161 A file based password, specified be prefix “file:” should be the path
162 of a file containing the password to be read by the tool or a “-” to
163 use stdin. Storing passwords in files prevents information leakage,
164 passwords passed as options can be read from the process list or common
165 shell history features.
166 Examples
168 # to use stdin and be prompted
169 file:-
170 # to use a file from a path
172 file:path/to/password/file
173 # to echo a password via stdin:
175 echo foobar | tpm2_tool -p file:-
176 # to use a bash here-string via stdin:
178 tpm2_tool -p file:- <<< foobar
180 Sessions
182 When using a policy session to authorize the use of an object, prefix
183 the option argument with the session keyword. Then indicate a path to
184 a session file that was created with tpm2_startauthsession(1). Option‐
185 ally, if the session requires an auth value to be sent with the session
186 handle (eg policy password), then append a + and a string as described
187 in the Passwords section.
188 Examples
190 To use a session context file called session.ctx.
191 session:session.ctx
193 To use a session context file called session.ctx AND send the authvalue
195 mypassword.
196 session:session.ctx+mypassword
198 To use a session context file called session.ctx AND send the HEX auth‐
200 value 0x11223344.
201 session:session.ctx+hex:11223344
203 PCR Authorizations
205 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
206 language. The PCR minilanguage is as follows:
207 <pcr-spec>=<raw-pcr-file>
208 The PCR spec is documented in in the section “PCR bank specifiers”.
210 The raw-pcr-file is an optional argument that contains the output of
212 the raw PCR contents as returned by tpm2_pcrread(1).
213 PCR bank specifiers (pcr.md)
215 Examples
217 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
218 er of:
219 pcr:sha256:0,1,2,3
221 specifying AUTH.
223
225 Options that take algorithms support “nice-names”.
226 There are two major algorithm specification string classes, simple and
228 complex. Only certain algorithms will be accepted by the TPM, based on
229 usage and conditions.
230 Simple specifiers
232 These are strings with no additional specification data. When creating
233 objects, non-specified portions of an object are assumed to defaults.
234 You can find the list of known “Simple Specifiers Below”.
235 Asymmetric
237 • rsa
238 • ecc
240 Symmetric
242 • aes
243 • camellia
245 Hashing Algorithms
247 • sha1
248 • sha256
250 • sha384
252 • sha512
254 • sm3_256
256 • sha3_256
258 • sha3_384
260 • sha3_512
262 Keyed Hash
264 • hmac
265 • xor
267 Signing Schemes
269 • rsassa
270 • rsapss
272 • ecdsa
274 • ecdaa
276 • ecschnorr
278 Asymmetric Encryption Schemes
280 • oaep
281 • rsaes
283 • ecdh
285 Modes
287 • ctr
288 • ofb
290 • cbc
292 • cfb
294 • ecb
296 Misc
298 • null
299 Complex Specifiers
301 Objects, when specified for creation by the TPM, have numerous algo‐
302 rithms to populate in the public data. Things like type, scheme and
303 asymmetric details, key size, etc. Below is the general format for
304 specifying this data: <type>:<scheme>:<symmetric-details>
305 Type Specifiers
307 This portion of the complex algorithm specifier is required. The re‐
308 maining scheme and symmetric details will default based on the type
309 specified and the type of the object being created.
310 • aes - Default AES: aes128
312 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
314 If mode is not specified, defaults to null.
315 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
317 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
319 • ecc - Elliptical Curve, defaults to ecc256.
321 • ecc192 - 192 bit ECC
323 • ecc224 - 224 bit ECC
325 • ecc256 - 256 bit ECC
327 • ecc384 - 384 bit ECC
329 • ecc521 - 521 bit ECC
331 • rsa - Default RSA: rsa2048
333 • rsa1024 - RSA with 1024 bit keysize.
335 • rsa2048 - RSA with 2048 bit keysize.
337 • rsa4096 - RSA with 4096 bit keysize.
339 Scheme Specifiers
341 Next, is an optional field, it can be skipped.
342 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
344 Most signing schemes take a hash algorithm directly following the sign‐
345 ing scheme. If the hash algorithm is missing, it defaults to sha256.
346 Some take no arguments, and some take multiple arguments.
347 Hash Optional Scheme Specifiers
349 These scheme specifiers are followed by a dash and a valid hash algo‐
350 rithm, For example: oaep-sha256.
351 • oaep
353 • ecdh
355 • rsassa
357 • rsapss
359 • ecdsa
361 • ecschnorr
363 Multiple Option Scheme Specifiers
365 This scheme specifier is followed by a count (max size UINT16) then
366 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
367 ecdaa4-sha256. If no count is specified, it defaults to 4.
368 No Option Scheme Specifiers
370 This scheme specifier takes NO arguments. * rsaes
371 Symmetric Details Specifiers
373 This field is optional, and defaults based on the type of object being
374 created and it’s attributes. Generally, any valid Symmetric specifier
375 from the Type Specifiers list should work. If not specified, an asym‐
376 metric objects symmetric details defaults to aes128cfb.
377 Examples
379 Create an rsa2048 key with an rsaes asymmetric encryption scheme
380 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
381 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
383 sha384 hash
384 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
385 key.priv cryptographic algorithms ALGORITHM.
386
388 Format selection for the signature output file. tss (the default) will
389 output a binary blob according to the TPM 2.0 specification and any po‐
390 tential compiler padding. The option plain will output the plain sig‐
391 nature data as defined by the used cryptographic algorithm. signature
392 FORMAT.
393
395 This collection of options are common to many programs and provide in‐
396 formation that many users may expect.
397 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
399 attempts to invoke the manpager for the tool, however, on failure
400 will output a short tool summary. This is the same behavior if the
401 “man” option argument is specified, however if explicit “man” is re‐
402 quested, the tool will provide errors from man on stderr. If the
403 “no-man” option if specified, or the manpager fails, the short op‐
404 tions will be output to stdout.
405 To successfully use the manpages feature requires the manpages to be
407 installed or on MANPATH, See man(1) for more details.
408 • -v, --version: Display version information for this tool, supported
410 tctis and exit.
411 • -V, --verbose: Increase the information that the tool prints to the
413 console during its execution. When using this option the file and
414 line number are printed.
415 • -Q, --quiet: Silence normal tool output to stdout.
417 • -Z, --enable-errata: Enable the application of errata fixups. Useful
419 if an errata fixup needs to be applied to commands sent to the TPM.
420 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
421 formation many users may expect.
422
424 The TCTI or “Transmission Interface” is the communication mechanism
425 with the TPM. TCTIs can be changed for communication with TPMs across
426 different mediums.
427 To control the TCTI, the tools respect:
429 1. The command line option -T or --tcti
431 2. The environment variable: TPM2TOOLS_TCTI.
433 Note: The command line option always overrides the environment vari‐
435 able.
436 The current known TCTIs are:
438 • tabrmd - The resource manager, called tabrmd
440 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
441 abrmd as a tcti name are synonymous.
442 • mssim - Typically used for communicating to the TPM software simula‐
444 tor.
445 • device - Used when talking directly to a TPM device file.
447 • none - Do not initalize a connection with the TPM. Some tools allow
449 for off-tpm options and thus support not using a TCTI. Tools that do
450 not support it will error when attempted to be used without a TCTI
451 connection. Does not support ANY options and MUST BE presented as
452 the exact text of “none”.
453 The arguments to either the command line option or the environment
455 variable are in the form:
456 <tcti-name>:<tcti-option-config>
458 Specifying an empty string for either the <tcti-name> or <tcti-op‐
460 tion-config> results in the default being used for that portion respec‐
461 tively.
462 TCTI Defaults
464 When a TCTI is not specified, the default TCTI is searched for using
465 dlopen(3) semantics. The tools will search for tabrmd, device and
466 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
467 what TCTI will be chosen as the default by using the -v option to print
468 the version information. The “default-tcti” key-value pair will indi‐
469 cate which of the aforementioned TCTIs is the default.
470 Custom TCTIs
472 Any TCTI that implements the dynamic TCTI interface can be loaded. The
473 tools internally use dlopen(3), and the raw tcti-name value is used for
474 the lookup. Thus, this could be a path to the shared library, or a li‐
475 brary name as understood by dlopen(3) semantics.
476
478 This collection of options are used to configure the various known TCTI
479 modules available:
480 • device: For the device TCTI, the TPM character device file for use by
482 the device TCTI can be specified. The default is /dev/tpm0.
483 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
485 vice:/dev/tpm0”
486 • mssim: For the mssim TCTI, the domain name or IP address and port
488 number used by the simulator can be specified. The default are
489 127.0.0.1 and 2321.
490 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
492 TI=“mssim:host=localhost,port=2321”
493 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
495 ries of simple key value pairs separated by a `,' character. Each
496 key and value string are separated by a `=' character.
497 • TCTI abrmd supports two keys:
499 1. `bus_name' : The name of the tabrmd service on the bus (a
501 string).
502 2. `bus_type' : The type of the dbus instance (a string) limited to
504 `session' and `system'.
505 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
507 ample.FooBar:
508 \--tcti=tabrmd:bus_name=com.example.FooBar
510 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
512 sion:
513 \--tcti:bus_type=session
515 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
517 ules.
518
520 Create an Attestation Key and make it persistent
521 tpm2_createek -c ek.handle -G rsa -u ek.pub
522 tpm2_createak -C ek.handle -c ak.ctx -u ak.pub -n ak.name
523 tpm2_evictcontrol -C o -c ak.ctx 0x81010002
524
526 Tools can return any of the following codes:
527 • 0 - Success.
529 • 1 - General non-specific error.
531 • 2 - Options handling error.
533 • 3 - Authentication error.
535 • 4 - TCTI related error.
537 • 5 - Non supported scheme. Applicable to tpm2_testparams.
539
541 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
542
544 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
545tpm2-tools tpm2_createak(1)