1tpm2_rsaencrypt(1) General Commands Manual tpm2_rsaencrypt(1)
2
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 The key referenced by key-context is required to be:
18 1. An RSA key
20 2. Have the attribute encrypt 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 encryption.
28 • -o, --output=FILE:
30 Optional output file path to record the encrypted data to. The de‐
32 fault is to print the binary encrypted data to stdout.
33 • -s, --scheme=FORMAT:
35 Optional, set the padding scheme (defaults to rsaes).
37 • null - TPM_ALG_NULL uses the key’s scheme if set.
39 • rsaes - TPM_ALG_RSAES which is RSAES_PKCSV1.5.
41 • oaep - TPM_ALG_OAEP which is RSAES_OAEP.
43 • -l, --label=FILE or STRING:
45 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 • ARGUMENT the command line argument specifies the path of the file
52 with data to be encrypted.
53 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 • If the argument is a file path, then the file is loaded as a restored
60 TPM transient object.
61 • If the argument is a prefix match on one of:
63 • owner: the owner hierarchy
65 • platform: the platform hierarchy
67 • endorsement: the endorsement hierarchy
69 • lockout: the lockout control persistent object
71 • 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 NOTE: “Authorizations default to the EMPTY PASSWORD when not speci‐
80 fied”.
81 Passwords
83 Passwords are interpreted in the following forms below using prefix
84 identifiers.
85 Note: By default passwords are assumed to be in the string form when
87 they do not have a prefix.
88 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 Examples
95 foobar
96 str:foobar
97 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 Example
104 hex:0x1122334455667788
105 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 Examples
114 # to use stdin and be prompted
115 file:-
116 # to use a file from a path
118 file:path/to/password/file
119 # to echo a password via stdin:
121 echo foobar | tpm2_tool -p file:-
122 # to use a bash here-string via stdin:
124 tpm2_tool -p file:- <<< foobar
126 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 Examples
136 To use a session context file called session.ctx.
137 session:session.ctx
139 To use a session context file called session.ctx AND send the authvalue
141 mypassword.
142 session:session.ctx+mypassword
144 To use a session context file called session.ctx AND send the HEX auth‐
146 value 0x11223344.
147 session:session.ctx+hex:11223344
149 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 The PCR spec is documented in in the section “PCR bank specifiers”.
156 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 PCR bank specifiers (pcr.md)
161 Examples
163 To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
164 er of:
165 pcr:sha256:0,1,2,3
167 specifying AUTH.
169
171 This collection of options are common to many programs and provide in‐
172 formation that many users may expect.
173 • -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 To successfully use the manpages feature requires the manpages to be
183 installed or on MANPATH, See man(1) for more details.
184 • -v, --version: Display version information for this tool, supported
186 tctis and exit.
187 • -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 • -Q, --quiet: Silence normal tool output to stdout.
193 • -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 To control the TCTI, the tools respect:
205 1. The command line option -T or --tcti
207 2. The environment variable: TPM2TOOLS_TCTI.
209 Note: The command line option always overrides the environment vari‐
211 able.
212 The current known TCTIs are:
214 • 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 • mssim - Typically used for communicating to the TPM software simula‐
220 tor.
221 • device - Used when talking directly to a TPM device file.
223 • 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 The arguments to either the command line option or the environment
231 variable are in the form:
232 <tcti-name>:<tcti-option-config>
234 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 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 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 • 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 Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“de‐
261 vice:/dev/tpm0”
262 • 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 Example: -T mssim:host=localhost,port=2321 or export TPM2TOOLS_TC‐
268 TI=“mssim:host=localhost,port=2321”
269 • 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 • TCTI abrmd supports two keys:
275 1. `bus_name' : The name of the tabrmd service on the bus (a
277 string).
278 2. `bus_type' : The type of the dbus instance (a string) limited to
280 `session' and `system'.
281 Specify the tabrmd tcti name and a config string of bus_name=com.ex‐
283 ample.FooBar:
284 \--tcti=tabrmd:bus_name=com.example.FooBar
286 Specify the default (abrmd) tcti and a config string of bus_type=ses‐
288 sion:
289 \--tcti:bus_type=session
291 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 Encrypt using RSA
302 echo "my message" > msg.dat
303 tpm2_rsaencrypt -c key.ctx -o msg.enc msg.dat
304 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 • 0 - Success.
314 • 1 - General non-specific error.
316 • 2 - Options handling error.
318 • 3 - Authentication error.
320 • 4 - TCTI related error.
322 • 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.01.org/mailman/listinfo/tpm2)
330tpm2-tools tpm2_rsaencrypt(1)