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 - A NIST_P256 key by default. Alternative curves can be se‐
44 lected using algorithm specifiers (e.g. ecc384 or ecc_nist_p384) .
45 • rsa - An RSA2048 key.
47 • keyedhash - hmac key.
49 • -g, --hash-algorithm=ALGORITHM:
51 Specifies the digest algorithm used for signing.
53 • -s, --signing-algorithm=ALGORITHM:
55 The signing algorithm.
57 • -u, --public=FILE:
59 The file to save the public portion of the attestation key.
61 • -n, --ak-name=FILE:
63 The file to save the attestation key name, optional.
65 • -r, --private=FILE:
67 The output file which contains the sensitive portion of the object,
69 optional. # Protection Details
70 Objects that can move outside of TPM need to be protected (confiden‐
72 tiality and integrity). For instance, transient objects require that
73 TPM protected data (key or seal material) be stored outside of the TPM.
74 This is seen in tools like tpm2_create(1), where the -r option outputs
75 this protected data. This blob contains the sensitive portions of the
76 object. The sensitive portions of the object are protected by the par‐
77 ent object, using the parent’s symmetric encryption details to encrypt
78 the sensitive data and HMAC it.
79 In-depth details can be found in sections 23 of:
81 • https://trustedcomputinggroup.org/wp-content/up‐
83 loads/TPM-Rev-2.0-Part-1-Architecture-01.38.pdf
84 Notably Figure 20, is relevant, even though it’s specifically referring
86 to duplication blobs, the process is identical.
87 If the output is from tpm2_duplicate(1), the output will be slightly
89 different, as described fully in section 23.
90 • -f, --format:
92 Format selection for the public key output file. `tss' (the default)
94 will output a binary blob according to the TPM 2.0 Specification.
95 `pem' will output an OpenSSL compatible PEM encoded public key.
96 `der' will output an OpenSSL compatible DER encoded public key.
97 `tpmt' will output a binary blob of the TPMT_PUBLIC struct referenced
98 by TPM 2.0 specs.
99 Format selection for the signature output file.
101 • -q, --ak-qualified-name=FILE:
103 The qualified name of the attestation key object. The qualified name
105 is the qualified name of the parent object (the EK in this instance)
106 and the name of the object itself. Thus, the qualified name of an
107 object serves to bind it to its parents.
108 References
111 The type of a context object, whether it is a handle or file name, is
112 determined according to the following logic in-order:
113 • If the argument is a file path, then the file is loaded as a restored
115 TPM transient object.
116 • If the argument is a prefix match on one of:
118 • owner: the owner hierarchy
120 • platform: the platform hierarchy
122 • endorsement: the endorsement hierarchy
124 • lockout: the lockout control persistent object
126 • If the argument argument can be loaded as a number it will be treat
128 as a handle, e.g. 0x81010013 and used directly._OBJECT_.
129
131 Authorization for use of an object in TPM2.0 can come in 3 different
132 forms: 1. Password 2. HMAC 3. Sessions
133 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
135 fied”.
136 Passwords
138 Passwords are interpreted in the following forms below using prefix
139 identifiers.
140 Note: By default passwords are assumed to be in the string form when
142 they do not have a prefix.
143 String
145 A string password, specified by prefix “str:” or it’s absence (raw
146 string without prefix) is not interpreted, and is directly used for au‐
147 thorization.
148 Examples
150 foobar
151 str:foobar
152 Hex-string
154 A hex-string password, specified by prefix “hex:” is converted from a
155 hexidecimal form into a byte array form, thus allowing passwords with
156 non-printable and/or terminal un-friendly characters.
157 Example
159 hex:1122334455667788
160 File
162 A file based password, specified be prefix “file:” should be the path
163 of a file containing the password to be read by the tool or a “-” to
164 use stdin. Storing passwords in files prevents information leakage,
165 passwords passed as options can be read from the process list or common
166 shell history features.
167 Examples
169 # to use stdin and be prompted
170 file:-
171 # to use a file from a path
173 file:path/to/password/file
174 # to echo a password via stdin:
176 echo foobar | tpm2_tool -p file:-
177 # to use a bash here-string via stdin:
179 tpm2_tool -p file:- <<< foobar
181 Sessions
183 When using a policy session to authorize the use of an object, prefix
184 the option argument with the session keyword. Then indicate a path to
185 a session file that was created with tpm2_startauthsession(1). Option‐
186 ally, if the session requires an auth value to be sent with the session
187 handle (eg policy password), then append a + and a string as described
188 in the Passwords section.
189 Examples
191 To use a session context file called session.ctx.
192 session:session.ctx
194 To use a session context file called session.ctx AND send the authvalue
196 mypassword.
197 session:session.ctx+mypassword
199 To use a session context file called session.ctx AND send the HEX auth‐
201 value 0x11223344.
202 session:session.ctx+hex:11223344
204 PCR Authorizations
206 You can satisfy a PCR policy using the “pcr:” prefix and the PCR mini‐
207 language. The PCR minilanguage is as follows:
208 <pcr-spec>=<raw-pcr-file>
209 The PCR spec is documented in in the section “PCR bank specifiers”.
211 The raw-pcr-file is an optional argument that contains the output of
213 the raw PCR contents as returned by tpm2_pcrread(1).
214 PCR bank specifiers (pcr.md)
216 Examples
218 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
219 er of:
220 pcr:sha256:0,1,2,3
222 specifying AUTH.
224
226 Options that take algorithms support “nice-names”.
227 There are two major algorithm specification string classes, simple and
229 complex. Only certain algorithms will be accepted by the TPM, based on
230 usage and conditions.
231 Simple specifiers
233 These are strings with no additional specification data. When creating
234 objects, non-specified portions of an object are assumed to defaults.
235 You can find the list of known “Simple Specifiers” below.
236 Asymmetric
238 • rsa
239 • ecc
241 Symmetric
243 • aes
244 • camellia
246 • sm4
248 Hashing Algorithms
250 • sha1
251 • sha256
253 • sha384
255 • sha512
257 • sm3_256
259 • sha3_256
261 • sha3_384
263 • sha3_512
265 Keyed Hash
267 • hmac
268 • xor
270 Signing Schemes
272 • rsassa
273 • rsapss
275 • ecdsa
277 • ecdaa
279 • ecschnorr
281 • sm2
283 Asymmetric Encryption Schemes
285 • oaep
286 • rsaes
288 • ecdh
290 Modes
292 • ctr
293 • ofb
295 • cbc
297 • cfb
299 • ecb
301 Misc
303 • null
304 Complex Specifiers
306 Objects, when specified for creation by the TPM, have numerous algo‐
307 rithms to populate in the public data. Things like type, scheme and
308 asymmetric details, key size, etc. Below is the general format for
309 specifying this data: <type>:<scheme>:<symmetric-details>
310 Type Specifiers
312 This portion of the complex algorithm specifier is required. The re‐
313 maining scheme and symmetric details will default based on the type
314 specified and the type of the object being created.
315 • aes - Default AES: aes128
317 • aes128<mode> - 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb).
319 If mode is not specified, defaults to null.
320 • aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
322 • aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
324 • sm4 - Default SM4: sm4128
326 • sm4128 or sm4_128 <mode> - 128 bit SM4 with optional mode
328 (ctr|ofb|cbc|cfb|ecb). If mode is not specified, defaults to null.
329 • ecc - Elliptical Curve, defaults to ecc256.
331 • ecc192 or ecc_nist_p192 - 192 bit ECC NIST curve
333 • ecc224 or ecc_nist_p224 - 224 bit ECC NIST curve
335 • ecc256 or ecc_nist_p256 - 256 bit ECC NIST curve
337 • ecc384 or ecc_nist_p384 - 384 bit ECC NIST curve
339 • ecc521 or ecc_nist_p521 - 521 bit ECC NIST curve
341 • ecc_sm2 or ecc_sm2_p256 - 256 bit SM2 curve
343 • rsa - Default RSA: rsa2048
345 • rsa1024 - RSA with 1024 bit keysize.
347 • rsa2048 - RSA with 2048 bit keysize.
349 • rsa3072 - RSA with 3072 bit keysize.
351 • rsa4096 - RSA with 4096 bit keysize.
353 Scheme Specifiers
355 Next, is an optional field, it can be skipped.
356 Schemes are usually Signing Schemes or Asymmetric Encryption Schemes.
358 Most signing schemes take a hash algorithm directly following the sign‐
359 ing scheme. If the hash algorithm is missing, it defaults to sha256.
360 Some take no arguments, and some take multiple arguments.
361 Hash Optional Scheme Specifiers
363 These scheme specifiers are followed by a dash and a valid hash algo‐
364 rithm, For example: oaep-sha256.
365 • oaep
367 • ecdh
369 • rsassa
371 • rsapss
373 • ecdsa
375 • ecschnorr
377 • sm2
379 Multiple Option Scheme Specifiers
381 This scheme specifier is followed by a count (max size UINT16) then
382 followed by a dash(-) and a valid hash algorithm. * ecdaa For example,
383 ecdaa4-sha256. If no count is specified, it defaults to 4.
384 No Option Scheme Specifiers
386 This scheme specifier takes NO arguments. * rsaes
387 Symmetric Details Specifiers
389 This field is optional, and defaults based on the type of object being
390 created and it’s attributes. Generally, any valid Symmetric specifier
391 from the Type Specifiers list should work. If not specified, an asym‐
392 metric objects symmetric details defaults to aes128cfb.
393 Examples
395 Create an rsa2048 key with an rsaes asymmetric encryption scheme
396 tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
397 Create an ecc256 key with an ecdaa signing scheme with a count of 4 and
399 sha384 hash
400 /tpm2_create -C parent.ctx -G ecc256:ecdaa4-sha384 -u key.pub -r
401 key.priv cryptographic algorithms ALGORITHM.
402
404 Format selection for the signature output file. tss (the default) will
405 output a binary blob according to the TPM 2.0 specification and any po‐
406 tential compiler padding. The option plain will output the plain sig‐
407 nature data as defined by the used cryptographic algorithm. signature
408 FORMAT.
409
411 This collection of options are common to many programs and provide in‐
412 formation that many users may expect.
413 • -h, --help=[man|no-man]: Display the tools manpage. By default, it
415 attempts to invoke the manpager for the tool, however, on failure
416 will output a short tool summary. This is the same behavior if the
417 “man” option argument is specified, however if explicit “man” is re‐
418 quested, the tool will provide errors from man on stderr. If the
419 “no-man” option if specified, or the manpager fails, the short op‐
420 tions will be output to stdout.
421 To successfully use the manpages feature requires the manpages to be
423 installed or on MANPATH, See man(1) for more details.
424 • -v, --version: Display version information for this tool, supported
426 tctis and exit.
427 • -V, --verbose: Increase the information that the tool prints to the
429 console during its execution. When using this option the file and
430 line number are printed.
431 • -Q, --quiet: Silence normal tool output to stdout.
433 • -Z, --enable-errata: Enable the application of errata fixups. Useful
435 if an errata fixup needs to be applied to commands sent to the TPM.
436 Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. in‐
437 formation many users may expect.
438
440 The TCTI or “Transmission Interface” is the communication mechanism
441 with the TPM. TCTIs can be changed for communication with TPMs across
442 different mediums.
443 To control the TCTI, the tools respect:
445 1. The command line option -T or --tcti
447 2. The environment variable: TPM2TOOLS_TCTI.
449 Note: The command line option always overrides the environment vari‐
451 able.
452 The current known TCTIs are:
454 • tabrmd - The resource manager, called tabrmd
456 (https://github.com/tpm2-software/tpm2-abrmd). Note that tabrmd and
457 abrmd as a tcti name are synonymous.
458 • mssim - Typically used for communicating to the TPM software simula‐
460 tor.
461 • device - Used when talking directly to a TPM device file.
463 • none - Do not initalize a connection with the TPM. Some tools allow
465 for off-tpm options and thus support not using a TCTI. Tools that do
466 not support it will error when attempted to be used without a TCTI
467 connection. Does not support ANY options and MUST BE presented as
468 the exact text of “none”.
469 The arguments to either the command line option or the environment
471 variable are in the form:
472 <tcti-name>:<tcti-option-config>
474 Specifying an empty string for either the <tcti-name> or <tcti-op‐
476 tion-config> results in the default being used for that portion respec‐
477 tively.
478 TCTI Defaults
480 When a TCTI is not specified, the default TCTI is searched for using
481 dlopen(3) semantics. The tools will search for tabrmd, device and
482 mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND. You can query
483 what TCTI will be chosen as the default by using the -v option to print
484 the version information. The “default-tcti” key-value pair will indi‐
485 cate which of the aforementioned TCTIs is the default.
486 Custom TCTIs
488 Any TCTI that implements the dynamic TCTI interface can be loaded. The
489 tools internally use dlopen(3), and the raw tcti-name value is used for
490 the lookup. Thus, this could be a path to the shared library, or a li‐
491 brary name as understood by dlopen(3) semantics.
492
494 This collection of options are used to configure the various known TCTI
495 modules available:
496 • device: For the device TCTI, the TPM character device file for use by
498 the device TCTI can be specified. The default is /dev/tpm0.
499 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
501 vice:/dev/tpm0”
502 • mssim: For the mssim TCTI, the domain name or IP address and port
504 number used by the simulator can be specified. The default are
505 127.0.0.1 and 2321.
506 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
508 TI=“mssim:host=localhost,port=2321”
509 • abrmd: For the abrmd TCTI, the configuration string format is a se‐
511 ries of simple key value pairs separated by a `,' character. Each
512 key and value string are separated by a `=' character.
513 • TCTI abrmd supports two keys:
515 1. `bus_name' : The name of the tabrmd service on the bus (a
517 string).
518 2. `bus_type' : The type of the dbus instance (a string) limited to
520 `session' and `system'.
521 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
523 ample.FooBar:
524 \--tcti=tabrmd:bus_name=com.example.FooBar
526 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
528 sion:
529 \--tcti:bus_type=session
531 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
533 ules.
534
536 Create an Attestation Key and make it persistent
537 tpm2_createek -c ek.handle -G rsa -u ek.pub
538 tpm2_createak -C ek.handle -c ak.ctx -u ak.pub -n ak.name
539 tpm2_evictcontrol -C o -c ak.ctx 0x81010002
540
542 Tools can return any of the following codes:
543 • 0 - Success.
545 • 1 - General non-specific error.
547 • 2 - Options handling error.
549 • 3 - Authentication error.
551 • 4 - TCTI related error.
553 • 5 - Non supported scheme. Applicable to tpm2_testparams.
555
557 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
558
560 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
561 fo/tpm2)
562tpm2-tools tpm2_createak(1)