1tpm2_rsaencrypt(1) General Commands Manual tpm2_rsaencrypt(1)
2
3
4
6 tpm2_rsaencrypt(1) - Performs an RSA encryption operation using the
7 TPM.
8
10 tpm2_rsaencrypt [OPTIONS] [ARGUMENT]
11
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
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
51 • ARGUMENT the command line argument specifies the path of the file
52 with data to be encrypted.
53
54 References
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
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
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
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
254 This collection of options are used to configure the various known TCTI
255 modules available:
256
257 • device: 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
263 • mssim: 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
270 • abrmd: 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
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
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
326 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
327
329 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
330 fo/tpm2)
331
332
333
334tpm2-tools tpm2_rsaencrypt(1)