1tpm2_encryptdecrypt(1)      General Commands Manual     tpm2_encryptdecrypt(1)
2
3
4

NAME

6       tpm2_encryptdecrypt(1) - Performs symmetric encryption or decryption.
7

SYNOPSIS

9       tpm2_encryptdecrypt [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_encryptdecrypt(1)  -  Performs  symmetric encryption or decryption
13       with a specified symmetric key on the contents of FILE.  If FILE is not
14       specified, defaults to stdin.
15

OPTIONS

17       · -c, --key-context=OBJECT:
18
19         The encryption key object.
20
21       · -p, --auth=AUTH:
22
23         The authorization value for the encryption key object.
24
25       · -d, --decrypt:
26
27         Perform a decrypt operation.  Defaults to encryption when this option
28         is not specified.
29
30       · -e, --pad:
31
32         Enable pkcs7 padding for applicable AES encryption modes cfb/cbc/ecb.
33         Applicable  only  to  encryption  and  for input data with last block
34         shorter than encryption block length.
35
36       · -o, --output=FILE or STDOUT:
37
38         The output file path for either the encrypted or decrypted data.   If
39         not specified, defaults to stdout.
40
41       · -G, --mode=ALGORITHM:
42
43         The  key  algorithm  associated with this object.  Defaults to object
44         properties or CFB if not defined.
45
46       · -t, --iv=FILE:
47
48         Optional initialization vector to use.  Defaults to 0's.  Syntax  al‐
49         lows  for  an input file and output file source to be specified.  The
50         input file path is first, optionally followed by a colon ":" and  the
51         output  iv  path.   This  output iv can be saved for subsequent calls
52         when chaining.
53
54       · --cphash=FILE
55
56         File path to record the hash of the command parameters.  This is com‐
57         monly termed as cpHash.  NOTE: When this option is selected, The tool
58         will not actually execute the command, it simply returns a cpHash.
59
60       · ARGUMENT the command line argument specifies the input file path FILE
61         of the data to encrypt or decrypt.
62
63   References

Context Object Format

65       The  type  of a context object, whether it is a handle or file name, is
66       determined according to the following logic in-order:
67
68       · If the argument is a file path, then the file is loaded as a restored
69         TPM transient object.
70
71       · If the argument is a prefix match on one of:
72
73         · owner: the owner hierarchy
74
75         · platform: the platform hierarchy
76
77         · endorsement: the endorsement hierarchy
78
79         · lockout: the lockout control persistent object
80
81       · If  the  argument argument can be loaded as a number it will be treat
82         as a handle, e.g.  0x81010013 and used directly.OBJECT.
83

Authorization Formatting

85       Authorization for use of an object in TPM2.0 can come  in  3  different
86       forms: 1.  Password 2.  HMAC 3.  Sessions
87
88       NOTE:  "Authorizations  default  to  the EMPTY PASSWORD when not speci‐
89       fied".
90
91   Passwords
92       Passwords are interpreted in the following  forms  below  using  prefix
93       identifiers.
94
95       Note:  By  default  passwords are assumed to be in the string form when
96       they do not have a prefix.
97
98   String
99       A string password, specified by prefix  "str:"  or  it's  absence  (raw
100       string without prefix) is not interpreted, and is directly used for au‐
101       thorization.
102
103   Examples
104              foobar
105              str:foobar
106
107   Hex-string
108       A hex-string password, specified by prefix "hex:" is converted  from  a
109       hexidecimal  form  into a byte array form, thus allowing passwords with
110       non-printable and/or terminal un-friendly characters.
111
112   Example
113              hex:0x1122334455667788
114
115   File
116       A file based password, specified be prefix "file:" should be  the  path
117       of  a  file  containing the password to be read by the tool or a "-" to
118       use stdin.  Storing passwords in files  prevents  information  leakage,
119       passwords passed as options can be read from the process list or common
120       shell history features.
121
122   Examples
123              # to use stdin and be prompted
124              file:-
125
126              # to use a file from a path
127              file:path/to/password/file
128
129              # to echo a password via stdin:
130              echo foobar | tpm2_tool -p file:-
131
132              # to use a bash here-string via stdin:
133
134              tpm2_tool -p file:- <<< foobar
135
136   Sessions
137       When using a policy session to authorize the use of an  object,  prefix
138       the  option argument with the session keyword.  Then indicate a path to
139       a session file that was created with tpm2_startauthsession(1).  Option‐
140       ally, if the session requires an auth value to be sent with the session
141       handle (eg policy password), then append a + and a string as  described
142       in the Passwords section.
143
144   Examples
145       To use a session context file called session.ctx.
146
147              session:session.ctx
148
149       To use a session context file called session.ctx AND send the authvalue
150       mypassword.
151
152              session:session.ctx+mypassword
153
154       To use a session context file called session.ctx AND send the HEX auth‐
155       value 0x11223344.
156
157              session:session.ctx+hex:11223344
158
159   PCR Authorizations
160       You  can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
161       language.      The     PCR     minilanguage     is     as      follows:
162       <pcr-spec>=<raw-pcr-file>
163
164       The PCR spec is documented in in the section "PCR bank specifiers".
165
166       The  raw-pcr-file  is an optional the output of the raw PCR contents as
167       returned by tpm2_pcrread(1).
168
169       PCR bank specifiers (common/pcr.md)
170
171   Examples
172       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
173       er of:
174
175              pcr:sha256:0,1,2,3
176
177       specifying AUTH.
178

Algorithm Specifiers

180       Options that take algorithms support "nice-names".
181
182       There  are two major algorithm specification string classes, simple and
183       complex.  Only certain algorithms will be accepted by the TPM, based on
184       usage and conditions.
185
186   Simple specifiers
187       These are strings with no additional specification data.  When creating
188       objects, non-specified portions of an object are assumed  to  defaults.
189       You can find the list of known "Simple Specifiers Below".
190
191   Asymmetric
192       · rsa
193
194       · ecc
195
196   Symmetric
197       · aes
198
199       · camellia
200
201   Hashing Algorithms
202       · sha1
203
204       · sha256
205
206       · sha384
207
208       · sha512
209
210       · sm3_256
211
212       · sha3_256
213
214       · sha3_384
215
216       · sha3_512
217
218   Keyed Hash
219       · hmac
220
221       · xor
222
223   Signing Schemes
224       · rsassa
225
226       · rsapss
227
228       · ecdsa
229
230       · ecdaa
231
232       · ecschnorr
233
234   Asymmetric Encryption Schemes
235       · oaep
236
237       · rsaes
238
239       · ecdh
240
241   Modes
242       · ctr
243
244       · ofb
245
246       · cbc
247
248       · cfb
249
250       · ecb
251
252   Misc
253       · null
254
255   Complex Specifiers
256       Objects,  when  specified  for creation by the TPM, have numerous algo‐
257       rithms to populate in the public data.  Things like  type,  scheme  and
258       asymmetric  details,  key  size,  etc.  Below is the general format for
259       specifying this data: <type>:<scheme>:<symmetric-details>
260
261   Type Specifiers
262       This portion of the complex algorithm specifier is required.   The  re‐
263       maining  scheme  and  symmetric  details will default based on the type
264       specified and the type of the object being created.
265
266       · aes - Default AES: aes128
267
268       · aes128<mode> - 128 bit AES with optional mode  (ctr|ofb|cbc|cfb|ecb).
269         If mode is not specified, defaults to null.
270
271       · aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
272
273       · aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
274
275       · ecc - Elliptical Curve, defaults to ecc256.
276
277       · ecc192 - 192 bit ECC
278
279       · ecc224 - 224 bit ECC
280
281       · ecc256 - 256 bit ECC
282
283       · ecc384 - 384 bit ECC
284
285       · ecc521 - 521 bit ECC
286
287       · rsa - Default RSA: rsa2048
288
289       · rsa1024 - RSA with 1024 bit keysize.
290
291       · rsa2048 - RSA with 2048 bit keysize.
292
293       · rsa4096 - RSA with 4096 bit keysize.
294
295   Scheme Specifiers
296       Next, is an optional field, it can be skipped.
297
298       Schemes  are  usually Signing Schemes or Asymmetric Encryption Schemes.
299       Most signing schemes take a hash algorithm directly following the sign‐
300       ing  scheme.   If the hash algorithm is missing, it defaults to sha256.
301       Some take no arguments, and some take multiple arguments.
302
303   Hash Optional Scheme Specifiers
304       These scheme specifiers are followed by a dash and a valid  hash  algo‐
305       rithm, For example: oaep-sha256.
306
307       · oaep
308
309       · ecdh
310
311       · rsassa
312
313       · rsapss
314
315       · ecdsa
316
317       · ecschnorr
318
319   Multiple Option Scheme Specifiers
320       This  scheme  specifier  is  followed by a count (max size UINT16) then
321       folloed by a dash(-) and a valid hash algorithm.  * ecdaa For  example,
322       ecdaa4-sha256.  If no count is specified, it defaults to 4.
323
324   No Option Scheme Specifiers
325       This scheme specifier takes NO arguments.  * rsaes
326
327   Symmetric Details Specifiers
328       This  field is optional, and defaults based on the type of object being
329       created and it's attributes.  Generally, any valid Symmetric  specifier
330       from  the Type Specifiers list should work.  If not specified, an asym‐
331       metric objects symmetric details defaults to aes128cfb.
332
333   Examples
334   Create an rsa2048 key with an rsaes asymmetric encryption scheme
335       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
336
337   Create an ecc256 key with an ecdaa signing scheme with a count of 4
338       and sha384 hash
339
340       /tpm2_create -C parent.ctx -G ecc256:ec‐
341       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
342

COMMON OPTIONS

344       This  collection of options are common to many programs and provide in‐
345       formation that many users may expect.
346
347       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
348         attempts  to  invoke  the  manpager for the tool, however, on failure
349         will output a short tool summary.  This is the same behavior  if  the
350         "man"  option argument is specified, however if explicit "man" is re‐
351         quested, the tool will provide errors from man  on  stderr.   If  the
352         "no-man"  option  if  specified, or the manpager fails, the short op‐
353         tions will be output to stdout.
354
355         To successfully use the manpages feature requires the manpages to  be
356         installed or on MANPATH, See man(1) for more details.
357
358       · -v,  --version:  Display version information for this tool, supported
359         tctis and exit.
360
361       · -V, --verbose: Increase the information that the tool prints  to  the
362         console  during  its  execution.  When using this option the file and
363         line number are printed.
364
365       · -Q, --quiet: Silence normal tool output to stdout.
366
367       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
368         if  an  errata fixup needs to be applied to commands sent to the TPM.
369         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
370         formation many users may expect.
371

TCTI Configuration

373       The  TCTI  or  "Transmission  Interface" is the communication mechanism
374       with the TPM.  TCTIs can be changed for communication with TPMs  across
375       different mediums.
376
377       To control the TCTI, the tools respect:
378
379       1. The command line option -T or --tcti
380
381       2. The environment variable: TPM2TOOLS_TCTI.
382
383       Note:  The  command  line option always overrides the environment vari‐
384       able.
385
386       The current known TCTIs are:
387
388       · tabrmd     -     The     resource     manager,     called      tabrmd
389         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
390         abrmd as a tcti name are synonymous.
391
392       · mssim - Typically used for communicating to the TPM software  simula‐
393         tor.
394
395       · device - Used when talking directly to a TPM device file.
396
397       · none  - Do not initalize a connection with the TPM.  Some tools allow
398         for off-tpm options and thus support not using a TCTI.  Tools that do
399         not  support  it  will error when attempted to be used without a TCTI
400         connection.  Does not support ANY options and MUST  BE  presented  as
401         the exact text of "none".
402
403       The  arguments  to  either  the  command line option or the environment
404       variable are in the form:
405
406       <tcti-name>:<tcti-option-config>
407
408       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
409       tion-config> results in the default being used for that portion respec‐
410       tively.
411
412   TCTI Defaults
413       When a TCTI is not specified, the default TCTI is  searched  for  using
414       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
415       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
416       what TCTI will be chosen as the default by using the -v option to print
417       the version information.  The "default-tcti" key-value pair will  indi‐
418       cate which of the aforementioned TCTIs is the default.
419
420   Custom TCTIs
421       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
422       tools internally use dlopen(3), and the raw tcti-name value is used for
423       the lookup.  Thus, this could be a path to the shared library, or a li‐
424       brary name as understood by dlopen(3) semantics.
425

TCTI OPTIONS

427       This collection of options are used to configure the various known TCTI
428       modules available:
429
430       · device: For the device TCTI, the TPM character device file for use by
431         the device TCTI can be specified.  The default is /dev/tpm0.
432
433         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
434         vice:/dev/tpm0"
435
436       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
437         number used by the simulator  can  be  specified.   The  default  are
438         127.0.0.1 and 2321.
439
440         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
441         TI="mssim:host=localhost,port=2321"
442
443       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
444         ries  of  simple  key value pairs separated by a ',' character.  Each
445         key and value string are separated by a '=' character.
446
447         · TCTI abrmd supports two keys:
448
449           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
450              string).
451
452           2. 'bus_type' : The type of the dbus instance (a string) limited to
453              'session' and 'system'.
454
455         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
456         ample.FooBar:
457
458         \--tcti=tabrmd:bus_name=com.example.FooBar
459
460         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
461         sion:
462
463         \--tcti:bus_type=session
464
465         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
466         ules.
467

EXAMPLES

Create an AES key

470              tpm2_createprimary -c primary.ctx
471              tpm2_create -C primary.ctx -Gaes128 -u key.pub -r key.priv
472              tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
473

Encrypt and Decrypt some data

475              echo "my secret" > secret.dat
476              tpm2_encryptdecrypt -c key.ctx -o secret.enc secret.dat
477              tpm2_encryptdecrypt -d -c key.ctx -o secret.dec secret.enc
478              cat secret.dec
479              my secret
480

Returns

482       Tools can return any of the following codes:
483
484       · 0 - Success.
485
486       · 1 - General non-specific error.
487
488       · 2 - Options handling error.
489
490       · 3 - Authentication error.
491
492       · 4 - TCTI related error.
493
494       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
495

BUGS

497       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
498

HELP

500       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
501
502
503
504tpm2-tools                                              tpm2_encryptdecrypt(1)
Impressum