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

NAME

6       tpm2_rsaencrypt(1)  -  Performs  an  RSA encryption operation using the
7       TPM.
8

SYNOPSIS

10       tpm2_rsaencrypt [OPTIONS] [ARGUMENT]
11

DESCRIPTION

13       tpm2_rsaencrypt(1) - Performs RSA encryption on the  contents  of  file
14       data  using  the  indicated  padding  scheme according to IETF RFC 3447
15       (PKCS#1).  Input 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 encrypt 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 encryption.
28
29-o, --output=FILE:
30
31         Optional  output  file path to record the encrypted data to.  The de‐
32         fault is to print the binary encrypted data to stdout.
33
34-s, --scheme=FORMAT:
35
36         Optional, set the padding scheme (defaults to rsaes).
37
38         • null - TPM_ALG_NULL uses the key’s scheme if set.
39
40         • rsaes - TPM_ALG_RSAES which is RSAES_PKCSV1.5.
41
42         • oaep - TPM_ALG_OAEP which is RSAES_OAEP.
43
44-l, --label=FILE or STRING:
45
46         Optional, set the label data.  Can either be a string or  file  path.
47         The  TPM requires the last byte of the label to be zero, this is han‐
48         dled internally to the tool.  No other embedded 0 bytes can exist  or
49         the TPM will truncate your label.
50
51ARGUMENT  the  command  line  argument specifies the path of the file
52         with data to be encrypted.
53
54   References

Context Object Format

56       The type of a context object, whether it is a handle or file  name,  is
57       determined according to the following logic in-order:
58
59       • If the argument is a file path, then the file is loaded as a restored
60         TPM transient object.
61
62       • If the argument is a prefix match on one of:
63
64         • owner: the owner hierarchy
65
66         • platform: the platform hierarchy
67
68         • endorsement: the endorsement hierarchy
69
70         • lockout: the lockout control persistent object
71
72       • If the argument argument can be loaded as a number it will  be  treat
73         as a handle, e.g. 0x81010013 and used directly._OBJECT_.
74

Authorization Formatting

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

COMMON OPTIONS

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

TCTI Configuration

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

TCTI OPTIONS

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

EXAMPLES

296   Create an RSA key and load it
297              tpm2_createprimary -c primary.ctx
298              tpm2_create -C primary.ctx -Grsa2048 -u key.pub -r key.priv
299              tpm2_load -C primary.ctx -u key.pub -r key.priv -c key.ctx
300
301   Encrypt using RSA
302              echo "my message" > msg.dat
303              tpm2_rsaencrypt -c key.ctx -o msg.enc msg.dat
304
305   Decrypt using RSA
306              tpm2_rsadecrypt -c key.ctx -o msg.ptext msg.enc
307              cat msg.ptext
308              my message
309

Returns

311       Tools can return any of the following codes:
312
313       • 0 - Success.
314
315       • 1 - General non-specific error.
316
317       • 2 - Options handling error.
318
319       • 3 - Authentication error.
320
321       • 4 - TCTI related error.
322
323       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
324

BUGS

326       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
327

HELP

329       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
330       fo/tpm2)
331
332
333
334tpm2-tools                                                  tpm2_rsaencrypt(1)
Impressum