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

NAME

6       tpm2_rsadecrypt(1)  -  Performs  an  RSA decryption operation using the
7       TPM.
8

SYNOPSIS

10       tpm2_rsadecrypt [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_rsadecrypt(1) - Performs RSA decryption on the  contents  of  file
14       using the indicated padding scheme according to IETF RFC 3447 (PKCS#1).
15       Command line argument defaults to stdin if not specified.
16
17       The key referenced by key-context is required to be:
18
19       1. An RSA key
20
21       2. Have the attribute decrypt SET in it’s attributes.
22

OPTIONS

24       • -c, --key-context=OBJECT:
25
26         Context object pointing to the the public portion of RSA key  to  use
27         for decryption.  Either a file or a handle number.  See section “Con‐
28         text Object Format”.
29
30       • -p, --auth=AUTH:
31
32         Optional authorization value to use the key specified by -c.
33
34       • -o, --output=FILE:
35
36         Optional output file path to record the decrypted data to.   The  de‐
37         fault is to print the binary encrypted data to STDOUT.
38
39       • -s, --scheme=FORMAT:
40
41         Optional, set the padding scheme (defaults to rsaes).
42
43         • null - TPM_ALG_NULL uses the key’s scheme if set.
44
45         • rsaes - TPM_ALG_RSAES which is RSAES_PKCSV1.5.
46
47         • oaep - TPM_ALG_OAEP which is RSAES_OAEP.
48
49       • -l, --label=FILE OR STRING:
50
51         Optional,  set  the  label data.The TPM requires the last byte of the
52         label to be zero, this is handled internally to the tool.   No  other
53         embedded 0 bytes can exist or the TPM will truncate your label.
54
55       • --cphash=FILE
56
57         File path to record the hash of the command parameters.  This is com‐
58         monly termed as cpHash.  NOTE: When this option is selected, The tool
59         will not actually execute the command, it simply returns a cpHash.
60
61       • ARGUMENT the command line argument specifies the file containing data
62         to be decrypted.
63
64   References

Context Object Format

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

Authorization Formatting

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

COMMON OPTIONS

181       This collection of options are common to many programs and provide  in‐
182       formation that many users may expect.
183
184       • -h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
185         attempts to invoke the manpager for the  tool,  however,  on  failure
186         will  output  a short tool summary.  This is the same behavior if the
187         “man” option argument is specified, however if explicit “man” is  re‐
188         quested,  the  tool  will  provide errors from man on stderr.  If the
189         “no-man” option if specified, or the manpager fails,  the  short  op‐
190         tions will be output to stdout.
191
192         To  successfully use the manpages feature requires the manpages to be
193         installed or on MANPATH, See man(1) for more details.
194
195       • -v, --version: Display version information for this  tool,  supported
196         tctis and exit.
197
198       • -V,  --verbose:  Increase the information that the tool prints to the
199         console during its execution.  When using this option  the  file  and
200         line number are printed.
201
202       • -Q, --quiet: Silence normal tool output to stdout.
203
204       • -Z, --enable-errata: Enable the application of errata fixups.  Useful
205         if an errata fixup needs to be applied to commands sent to  the  TPM.
206         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
207         formation many users may expect.
208

TCTI Configuration

210       The TCTI or “Transmission Interface”  is  the  communication  mechanism
211       with  the TPM.  TCTIs can be changed for communication with TPMs across
212       different mediums.
213
214       To control the TCTI, the tools respect:
215
216       1. The command line option -T or --tcti
217
218       2. The environment variable: TPM2TOOLS_TCTI.
219
220       Note: The command line option always overrides  the  environment  vari‐
221       able.
222
223       The current known TCTIs are:
224
225       • tabrmd      -     The     resource     manager,     called     tabrmd
226         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
227         abrmd as a tcti name are synonymous.
228
229       • mssim  - Typically used for communicating to the TPM software simula‐
230         tor.
231
232       • device - Used when talking directly to a TPM device file.
233
234       • none - Do not initalize a connection with the TPM.  Some tools  allow
235         for off-tpm options and thus support not using a TCTI.  Tools that do
236         not support it will error when attempted to be used  without  a  TCTI
237         connection.   Does  not  support ANY options and MUST BE presented as
238         the exact text of “none”.
239
240       The arguments to either the command  line  option  or  the  environment
241       variable are in the form:
242
243       <tcti-name>:<tcti-option-config>
244
245       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
246       tion-config> results in the default being used for that portion respec‐
247       tively.
248
249   TCTI Defaults
250       When  a  TCTI  is not specified, the default TCTI is searched for using
251       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
252       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
253       what TCTI will be chosen as the default by using the -v option to print
254       the  version information.  The “default-tcti” key-value pair will indi‐
255       cate which of the aforementioned TCTIs is the default.
256
257   Custom TCTIs
258       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
259       tools internally use dlopen(3), and the raw tcti-name value is used for
260       the lookup.  Thus, this could be a path to the shared library, or a li‐
261       brary name as understood by dlopen(3) semantics.
262

TCTI OPTIONS

264       This collection of options are used to configure the various known TCTI
265       modules available:
266
267       • device: For the device TCTI, the TPM character device file for use by
268         the device TCTI can be specified.  The default is /dev/tpm0.
269
270         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
271         vice:/dev/tpm0”
272
273       • mssim: For the mssim TCTI, the domain name or  IP  address  and  port
274         number  used  by  the  simulator  can  be specified.  The default are
275         127.0.0.1 and 2321.
276
277         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
278         TI=“mssim:host=localhost,port=2321”
279
280       • abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
281         ries of simple key value pairs separated by a  `,'  character.   Each
282         key and value string are separated by a `=' character.
283
284         • TCTI abrmd supports two keys:
285
286           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
287              string).
288
289           2. `bus_type' : The type of the dbus instance (a string) limited to
290              `session' and `system'.
291
292         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
293         ample.FooBar:
294
295                \--tcti=tabrmd:bus_name=com.example.FooBar
296
297         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298         sion:
299
300                \--tcti:bus_type=session
301
302         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
303         ules.
304

EXAMPLES

306   Create an RSA key and load it
307              tpm2_createprimary -c primary.ctx
308              tpm2_create -C primary.ctx -Grsa2048 -u key.pub -r key.priv
309              tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
310
311   Encrypt using RSA
312              echo "my message" > msg.dat
313              tpm2_rsaencrypt -c key.ctx -o msg.enc msg.dat
314
315   Decrypt using RSA
316              tpm2_rsadecrypt -c key.ctx -o msg.ptext msg.enc
317              cat msg.ptext
318              my message
319

Returns

321       Tools can return any of the following codes:
322
323       • 0 - Success.
324
325       • 1 - General non-specific error.
326
327       • 2 - Options handling error.
328
329       • 3 - Authentication error.
330
331       • 4 - TCTI related error.
332
333       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
334

BUGS

336       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
337

HELP

339       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
340
341
342
343tpm2-tools                                                  tpm2_rsadecrypt(1)