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

NAME

6       tpm2_readpublic(1) - Read the public area of a loaded object.
7

SYNOPSIS

9       tpm2_readpublic [OPTIONS]
10

DESCRIPTION

12       tpm2_readpublic(1) - Reads the public area of a loaded object.
13

OPTIONS

15-c, --object-context=OBJECT:
16
17         Context object for the object to read.
18
19-n, --name=FILE:
20
21         An optional file to save the name structure of the object.
22
23-f, --format:
24
25         Format selection for the public key output file.  `tss' (the default)
26         will output a binary blob according to  the  TPM  2.0  Specification.
27         `pem'  will  output  an  OpenSSL  compatible  PEM encoded public key.
28         `der' will output an  OpenSSL  compatible  DER  encoded  public  key.
29         `tpmt' will output a binary blob of the TPMT_PUBLIC struct referenced
30         by TPM 2.0 specs.
31
32         Public key format.
33
34-o, --output=FILE:
35
36         The output file path, recording the public portion of the object.
37
38-t, --serialized-handle=HANDLE:
39
40         If the object to be read is a persistent object specified  by  a  raw
41         handle,  optionally  save  the serialized handle for use later.  This
42         routine does NOT verify the name of the object being  read.   Callers
43         should  ensure  that  the contents of name match the expected objects
44         name.
45
46-q, --qualified-name=FILE:
47
48         Saves the qualified name of the object to FILE.  The  qualified  name
49         of the object is the name algorithm hash of the parents qualified and
50         the objects name.  Thus the qualified name of the  object  serves  as
51         proof of the objects parents.
52
53   References

Context Object Format

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

COMMON OPTIONS

75       This collection of options are common to many programs and provide  in‐
76       formation that many users may expect.
77
78-h,  --help=[man|no-man]:  Display the tools manpage.  By default, it
79         attempts to invoke the manpager for the  tool,  however,  on  failure
80         will  output  a short tool summary.  This is the same behavior if the
81         “man” option argument is specified, however if explicit “man” is  re‐
82         quested,  the  tool  will  provide errors from man on stderr.  If the
83         “no-man” option if specified, or the manpager fails,  the  short  op‐
84         tions will be output to stdout.
85
86         To  successfully use the manpages feature requires the manpages to be
87         installed or on MANPATH, See man(1) for more details.
88
89-v, --version: Display version information for this  tool,  supported
90         tctis and exit.
91
92-V,  --verbose:  Increase the information that the tool prints to the
93         console during its execution.  When using this option  the  file  and
94         line number are printed.
95
96-Q, --quiet: Silence normal tool output to stdout.
97
98-Z, --enable-errata: Enable the application of errata fixups.  Useful
99         if an errata fixup needs to be applied to commands sent to  the  TPM.
100         Defining  the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.  in‐
101         formation many users may expect.
102

TCTI Configuration

104       The TCTI or “Transmission Interface”  is  the  communication  mechanism
105       with  the TPM.  TCTIs can be changed for communication with TPMs across
106       different mediums.
107
108       To control the TCTI, the tools respect:
109
110       1. The command line option -T or --tcti
111
112       2. The environment variable: TPM2TOOLS_TCTI.
113
114       Note: The command line option always overrides  the  environment  vari‐
115       able.
116
117       The current known TCTIs are:
118
119       • tabrmd      -     The     resource     manager,     called     tabrmd
120         (https://github.com/tpm2-software/tpm2-abrmd).  Note that tabrmd  and
121         abrmd as a tcti name are synonymous.
122
123       • mssim  - Typically used for communicating to the TPM software simula‐
124         tor.
125
126       • device - Used when talking directly to a TPM device file.
127
128       • none - Do not initalize a connection with the TPM.  Some tools  allow
129         for off-tpm options and thus support not using a TCTI.  Tools that do
130         not support it will error when attempted to be used  without  a  TCTI
131         connection.   Does  not  support ANY options and MUST BE presented as
132         the exact text of “none”.
133
134       The arguments to either the command  line  option  or  the  environment
135       variable are in the form:
136
137       <tcti-name>:<tcti-option-config>
138
139       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op‐
140       tion-config> results in the default being used for that portion respec‐
141       tively.
142
143   TCTI Defaults
144       When  a  TCTI  is not specified, the default TCTI is searched for using
145       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
146       mssim  TCTIs  IN THAT ORDER and USE THE FIRST ONE FOUND.  You can query
147       what TCTI will be chosen as the default by using the -v option to print
148       the  version information.  The “default-tcti” key-value pair will indi‐
149       cate which of the aforementioned TCTIs is the default.
150
151   Custom TCTIs
152       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
153       tools internally use dlopen(3), and the raw tcti-name value is used for
154       the lookup.  Thus, this could be a path to the shared library, or a li‐
155       brary name as understood by dlopen(3) semantics.
156

TCTI OPTIONS

158       This collection of options are used to configure the various known TCTI
159       modules available:
160
161device: For the device TCTI, the TPM character device file for use by
162         the device TCTI can be specified.  The default is /dev/tpm0.
163
164         Example:    -T   device:/dev/tpm0   or   export   TPM2TOOLS_TCTI=“de‐
165         vice:/dev/tpm0”
166
167mssim: For the mssim TCTI, the domain name or  IP  address  and  port
168         number  used  by  the  simulator  can  be specified.  The default are
169         127.0.0.1 and 2321.
170
171         Example: -T mssim:host=localhost,port=2321  or  export  TPM2TOOLS_TC‐
172         TI=“mssim:host=localhost,port=2321”
173
174abrmd:  For  the abrmd TCTI, the configuration string format is a se‐
175         ries of simple key value pairs separated by a  `,'  character.   Each
176         key and value string are separated by a `=' character.
177
178         • TCTI abrmd supports two keys:
179
180           1. `bus_name'  :  The  name  of  the  tabrmd  service on the bus (a
181              string).
182
183           2. `bus_type' : The type of the dbus instance (a string) limited to
184              `session' and `system'.
185
186         Specify  the tabrmd tcti name and a config string of bus_name=com.ex‐
187         ample.FooBar:
188
189                \--tcti=tabrmd:bus_name=com.example.FooBar
190
191         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
192         sion:
193
194                \--tcti:bus_type=session
195
196         NOTE:  abrmd  and tabrmd are synonymous.  the various known TCTI mod‐
197         ules.  # EXAMPLES
198
199   Create a primary object and read the public structure in an openssl compli‐
200       ant format
201              tpm2_createprimary -c primary.ctx
202              tpm2_readpublic -c primary.ctx -o output.dat -f pem
203
204   Serialize an existing persistent object handle to disk for later use
205       This  work-flow  is  primarily intended for existing persistent TPM ob‐
206       jects.  This work-flow does not verify that the name of the  serialized
207       object  matches  the  expected, and thus the serialized handle could be
208       pointing to an attacker controlled object if no verification  is  done.
209       If  you are creating an object from scratch, save the serialized handle
210       when making the object persistent.
211
212       We assume that an object has already been persisted, for example via:
213
214              # We assume that an object has already been persisted, for example
215              tpm2_createprimary -c primary.ctx
216
217              # context files have all the information for the TPM to verify the object
218              tpm2_evictcontrol -c primary.ctx
219              persistent-handle: 0x81000001
220              action: persisted
221
222       Next use the persistent handle to get a serialized handle:
223
224              # The persistent handle output could be at an attacker controlled object,
225              # best practice is to use the option "-o: for tpm2_evictcontrol to get a
226              # serialized handle instead.
227
228              tpm2_readpublic -c 0x81000001 -o output.dat -f pem -t primary.handle
229
230              # use this verified handle in an encrypted session with the tpm
231              tpm2_startauthsession --policy-session -S session.ctx -c primary.handle
232
233       For new objects, its best to use all serialized handles.
234

Returns

236       Tools can return any of the following codes:
237
238       • 0 - Success.
239
240       • 1 - General non-specific error.
241
242       • 2 - Options handling error.
243
244       • 3 - Authentication error.
245
246       • 4 - TCTI related error.
247
248       • 5 - Non supported scheme.  Applicable to tpm2_testparams.
249

BUGS

251       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
252

HELP

254       See the Mailing List (https://lists.linuxfoundation.org/mailman/listin
255       fo/tpm2)
256
257
258
259tpm2-tools                                                  tpm2_readpublic(1)
Impressum