1tpm2_rsadecrypt(1) General Commands Manual tpm2_rsadecrypt(1)
2
6 tpm2_rsadecrypt(1) - Performs an RSA decryption operation using the
7 TPM.
8
10 tpm2_rsadecrypt [OPTIONS] [ARGUMENT]
11
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 The key referenced by key-context is required to be:
18 1. An RSA key
20 2. Have the attribute decrypt SET in it’s attributes.
22
24 • -c, --key-context=OBJECT:
25 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 • -p, --auth=AUTH:
31 Optional authorization value to use the key specified by -c.
33 • -o, --output=FILE:
35 Optional output file path to record the decrypted data to. The de‐
37 fault is to print the binary encrypted data to STDOUT.
38 • -s, --scheme=FORMAT:
40 Optional, set the padding scheme (defaults to rsaes).
42 • null - TPM_ALG_NULL uses the key’s scheme if set.
44 • rsaes - TPM_ALG_RSAES which is RSAES_PKCSV1.5.
46 • oaep - TPM_ALG_OAEP which is RSAES_OAEP.
48 • -l, --label=FILE OR STRING:
50 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 • --cphash=FILE
56 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 • ARGUMENT the command line argument specifies the file containing data
62 to be decrypted.
63 References
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 • If the argument is a file path, then the file is loaded as a restored
70 TPM transient object.
71 • If the argument is a prefix match on one of:
73 • owner: the owner hierarchy
75 • platform: the platform hierarchy
77 • endorsement: the endorsement hierarchy
79 • lockout: the lockout control persistent object
81 • 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
86 Authorization for use of an object in TPM2.0 can come in 3 different
87 forms: 1. Password 2. HMAC 3. Sessions
88 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
90 fied”.
91 Passwords
93 Passwords are interpreted in the following forms below using prefix
94 identifiers.
95 Note: By default passwords are assumed to be in the string form when
97 they do not have a prefix.
98 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 Examples
105 foobar
106 str:foobar
107 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 Example
114 hex:1122334455667788
115 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 Examples
124 # to use stdin and be prompted
125 file:-
126 # to use a file from a path
128 file:path/to/password/file
129 # to echo a password via stdin:
131 echo foobar | tpm2_tool -p file:-
132 # to use a bash here-string via stdin:
134 tpm2_tool -p file:- <<< foobar
136 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 Examples
146 To use a session context file called session.ctx.
147 session:session.ctx
149 To use a session context file called session.ctx AND send the authvalue
151 mypassword.
152 session:session.ctx+mypassword
154 To use a session context file called session.ctx AND send the HEX auth‐
156 value 0x11223344.
157 session:session.ctx+hex:11223344
159 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 The PCR spec is documented in in the section “PCR bank specifiers”.
166 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 PCR bank specifiers (pcr.md)
171 Examples
173 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
174 er of:
175 pcr:sha256:0,1,2,3
177 specifying AUTH.
179
181 This collection of options are common to many programs and provide in‐
182 formation that many users may expect.
183 • -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 To successfully use the manpages feature requires the manpages to be
193 installed or on MANPATH, See man(1) for more details.
194 • -v, --version: Display version information for this tool, supported
196 tctis and exit.
197 • -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 • -Q, --quiet: Silence normal tool output to stdout.
203 • -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
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 To control the TCTI, the tools respect:
215 1. The command line option -T or --tcti
217 2. The environment variable: TPM2TOOLS_TCTI.
219 Note: The command line option always overrides the environment vari‐
221 able.
222 The current known TCTIs are:
224 • 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 • mssim - Typically used for communicating to the TPM software simula‐
230 tor.
231 • device - Used when talking directly to a TPM device file.
233 • 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 The arguments to either the command line option or the environment
241 variable are in the form:
242 <tcti-name>:<tcti-option-config>
244 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 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 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
264 This collection of options are used to configure the various known TCTI
265 modules available:
266 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
271 vice:/dev/tpm0”
272 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
278 TI=“mssim:host=localhost,port=2321”
279 • 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 • TCTI abrmd supports two keys:
285 1. `bus_name' : The name of the tabrmd service on the bus (a
287 string).
288 2. `bus_type' : The type of the dbus instance (a string) limited to
290 `session' and `system'.
291 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
293 ample.FooBar:
294 \--tcti=tabrmd:bus_name=com.example.FooBar
296 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
298 sion:
299 \--tcti:bus_type=session
301 NOTE: abrmd and tabrmd are synonymous. the various known TCTI mod‐
303 ules.
304
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 Encrypt using RSA
312 echo "my message" > msg.dat
313 tpm2_rsaencrypt -c key.ctx -o msg.enc msg.dat
314 Decrypt using RSA
316 tpm2_rsadecrypt -c key.ctx -o msg.ptext msg.enc
317 cat msg.ptext
318 my message
319
321 Tools can return any of the following codes:
322 • 0 - Success.
324 • 1 - General non-specific error.
326 • 2 - Options handling error.
328 • 3 - Authentication error.
330 • 4 - TCTI related error.
332 • 5 - Non supported scheme. Applicable to tpm2_testparams.
334
336 Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
337
339 See the Mailing List (https://lists.linuxfoundation.org/mailman/listin‐
340 fo/tpm2)
341tpm2-tools tpm2_rsadecrypt(1)