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 the output of the raw PCR contents as
212 returned by tpm2_pcrread(1).
213 PCR bank specifiers (common/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
383 and sha384 hash
384 /tpm2_create -C parent.ctx -G ecc256:ec‐
386 daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
387
389 Format selection for the signature output file. tss (the default) will
390 output a binary blob according to the TPM 2.0 specification and any po‐
391 tential compiler padding. The option plain will output the plain sig‐
392 nature data as defined by the used cryptographic algorithm. signature
393 FORMAT.
394
396 This collection of options are common to many programs and provide in‐
397 formation that many users may expect.
398 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
400 attempts to invoke the manpager for the tool, however, on failure
401 will output a short tool summary. This is the same behavior if the
402 "man" option argument is specified, however if explicit "man" is re‐
403 quested, the tool will provide errors from man on stderr. If the
404 "no-man" option if specified, or the manpager fails, the short op‐
405 tions will be output to stdout.
406 To successfully use the manpages feature requires the manpages to be
408 installed or on MANPATH, See man(1) for more details.
409 • -v, --version: Display version information for this tool, supported
411 tctis and exit.
412 • -V, --verbose: Increase the information that the tool prints to the
414 console during its execution. When using this option the file and
415 line number are printed.
416 • -Q, --quiet: Silence normal tool output to stdout.
418 • -Z, --enable-errata: Enable the application of errata fixups. Useful
420 if an errata fixup needs to be applied to commands sent to the TPM.
421 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
422 formation many users may expect.
423
425 The TCTI or "Transmission Interface" is the communication mechanism
426 with the TPM. TCTIs can be changed for communication with TPMs across
427 different mediums.
428 To control the TCTI, the tools respect:
430 1. The command line option -T or --tcti
432 2. The environment variable: TPM2TOOLS_TCTI.
434 Note: The command line option always overrides the environment vari‐
436 able.
437 The current known TCTIs are:
439 • tabrmd - The resource manager, called tabrmd
441 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
442 abrmd as a tcti name are synonymous.
443 • mssim - Typically used for communicating to the TPM software simula‐
445 tor.
446 • device - Used when talking directly to a TPM device file.
448 • none - Do not initalize a connection with the TPM. Some tools allow
450 for off-tpm options and thus support not using a TCTI. Tools that do
451 not support it will error when attempted to be used without a TCTI
452 connection. Does not support ANY options and MUST BE presented as
453 the exact text of "none".
454 The arguments to either the command line option or the environment
456 variable are in the form:
457 <tcti-name>:<tcti-option-config>
459 Specifying an empty string for either the <tcti-name> or <tcti-op‐
461 tion-config> results in the default being used for that portion respec‐
462 tively.
463 TCTI Defaults
465 When a TCTI is not specified, the default TCTI is searched for using
466 dlopen(3) semantics. The tools will search for tabrmd, device and
467 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
468 what TCTI will be chosen as the default by using the -v option to print
469 the version information. The "default-tcti" key-value pair will indi‐
470 cate which of the aforementioned TCTIs is the default.
471 Custom TCTIs
473 Any TCTI that implements the dynamic TCTI interface can be loaded. The
474 tools internally use dlopen(3), and the raw tcti-name value is used for
475 the lookup. Thus, this could be a path to the shared library, or a li‐
476 brary name as understood by dlopen(3) semantics.
477
479 This collection of options are used to configure the various known TCTI
480 modules available:
481 • device: For the device TCTI, the TPM character device file for use by
483 the device TCTI can be specified. The default is /dev/tpm0.
484 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI="de‐
486 vice:/dev/tpm0"
487 • mssim: For the mssim TCTI, the domain name or IP address and port
489 number used by the simulator can be specified. The default are
490 127.0.0.1 and 2321.
491 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
493 TI="mssim:host=localhost,port=2321"
494 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
496 ries of simple key value pairs separated by a ',' character. Each
497 key and value string are separated by a '=' character.
498 • TCTI abrmd supports two keys:
500 1. 'bus_name' : The name of the tabrmd service on the bus (a
502 string).
503 2. 'bus_type' : The type of the dbus instance (a string) limited to
505 'session' and 'system'.
506 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
508 ample.FooBar:
509 \--tcti=tabrmd:bus_name=com.example.FooBar
511 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
513 sion:
514 \--tcti:bus_type=session
516 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
518 ules.
519
521 Create an Attestation Key and make it persistent
522 tpm2_createek -c ek.handle -G rsa -u ek.pub
523 tpm2_createak -C ek.handle -c ak.ctx -u ak.pub -n ak.name
524 tpm2_evictcontrol -C o -c ak.ctx 0x81010002
525
527 Tools can return any of the following codes:
528 • 0 - Success.
530 • 1 - General non-specific error.
532 • 2 - Options handling error.
534 • 3 - Authentication error.
536 • 4 - TCTI related error.
538 • 5 - Non supported scheme. Applicable to tpm2_testparams.
540
542 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
543
545 See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
546tpm2-tools tpm2_createak(1)