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

NAME

6       tpm2_unseal(1) - Returns the data in a loaded Sealed Data Object.
7

SYNOPSIS

9       tpm2_unseal [OPTIONS]
10

DESCRIPTION

12       tpm2_unseal(1) - -returns the data in a loaded Sealed Data Object.
13
14       NOTE: The –set-list and –pcr-input-file options should only be used for
15       simple PCR authentication policies.   For  more  complex  policies  the
16       tools  should be ran in an execution environment that keeps the session
17       context alive and pass that session using the –input-session-handle op‐
18       tion.
19

OPTIONS

21       · -H, –item=ITEM_HANDLE:
22
23         Item handle of loaded object.
24
25       · -c, –item-context=ITEM_CONTEXT_FILE:
26
27         Filename of the item context.
28
29       · -P, –pwdk=KEY_PASSWORD:
30
31         Specifies  the  password of ITEM_HANDLE.  Passwords should follow the
32         password formatting standards, see section “Password Formatting”.
33
34       · -o, –outfile=OUT_FILE:
35
36         Output file name, containing the unsealed data.  Defaults  to  stdout
37         if not specified.
38
39       · -S, –input-session-handle=SESSION_HANDLE:
40
41         Optional  Input  session  handle from a policy session for authoriza‐
42         tion.
43
44       · -L, –set-list==PCR_SELECTION_LIST:
45
46         The list of pcr banks and  selected  PCRs'  ids.   PCR_SELECTION_LIST
47         values  should  follow the pcr bank specifiers standards, see section
48         “PCR Bank Specfiers”.
49
50       · -F,**–pcr-input-file=PCR_INPUT_FILE
51
52         Optional Path or Name of the file containing expected pcr values  for
53         the specified index.  Default is to read the current PCRs per the set
54         list.
55

COMMON OPTIONS

57       This collection of options are common to many programs and provide  in‐
58       formation that many users may expect.
59
60       · -h,  –help: Display the tools manpage.  This requires the manpages to
61         be installed or on MANPATH, See man(1) for more details.
62
63       · -v, –version: Display version information for  this  tool,  supported
64         tctis and exit.
65
66       · -V,  –verbose:  Increase  the information that the tool prints to the
67         console during its execution.  When using this option  the  file  and
68         line number are printed.
69
70       · -Q, –quiet: Silence normal tool output to stdout.
71
72       · -Z,  –enable-errata: Enable the application of errata fixups.  Useful
73         if an errata fixup needs to be applied to commands sent to  the  TPM.
74         # TCTI ENVIRONMENT
75
76       This  collection of environment variables that may be used to configure
77       the various TCTI modules available.
78
79       The values passed through  these  variables  can  be  overridden  on  a
80       per-command basis using the available command line options, see the TC‐
81       TI_OPTIONS section.
82
83       The variables respected depend on how the software was configured.
84
85       · TPM2TOOLS_TCTI_NAME: Select the TCTI used for communication with  the
86         next  component down the TSS stack.  In most configurations this will
87         be the TPM but it could be a simulator or proxy.  The  current  known
88         TCTIs are:
89
90         · tabrmd    -    The    new    resource    manager,   called   tabrmd
91           (https://github.com/01org/tpm2-abrmd).
92
93         · socket - Typically used with the old resource manager,  or  talking
94           directly to a simulator.
95
96         · device - Used when talking directly to a TPM device file.
97
98       · TPM2TOOLS_DEVICE_FILE:  When  using  the device TCTI, specify the TPM
99         device file.  The default is “/dev/tpm0”.
100
101         Note: Using the tpm directly requires the users to ensure  that  con‐
102         current access does not occur and that they manage the tpm resources.
103         These tasks are usually managed by a resource  manager.   Linux  4.12
104         and  greater  supports an in kernel resource manager at “/dev/tpmrm”,
105         typically “/dev/tpmrm0”.
106
107       · TPM2TOOLS_SOCKET_ADDRESS: When using the socket TCTI, specify the do‐
108         main name or IP address used.  The default is 127.0.0.1.
109
110       · TPM2TOOLS_SOCKET_PORT:  When  using the socket TCTI, specify the port
111         number used.  The default is 2321.
112

TCTI OPTIONS

114       This collection of options are used to configure the varous  TCTI  mod‐
115       ules available.  They override any environment variables.
116
117       · -T, –tcti=TCTI_NAME[:TCTI_OPTIONS]: Select the TCTI used for communi‐
118         cation with the next component down the TSS stack.  In most  configu‐
119         rations    this    will    be    the    resource    manager:   tabrmd
120         (https://github.com/01org/tpm2-abrmd) Optionally, tcti  specific  op‐
121         tions can appended to TCTI_NAME by appending a : to TCTI_NAME.
122
123         · For the device TCTI, the TPM device file for use by the device TCTI
124           can be specified.  The  default  is  /dev/tpm0.   Example:  -T  de‐
125           vice:/dev/tpm0
126
127         · For  the socket TCTI, the domain name or IP address and port number
128           used by the socket can be specified.  The default are 127.0.0.1 and
129           2321.  Example: -T socket:127.0.0.1:2321
130
131         · For the abrmd TCTI, it takes no options.  Example: -T abrmd
132

Password Formatting

134       Passwords  are  interpreted  in  two  forms,  string and hex-string.  A
135       string password is not interpreted, and is directly used for authoriza‐
136       tion.   A  hex-string, is converted from a hexidecimal form into a byte
137       array form, thus allowing passwords with non-printable and/or  terminal
138       un-friendly characters.
139
140       By  default  passwords  are assumed to be in the string form.  Password
141       form is specified with special prefix values, they are:
142
143       · str: - Used to indicate it is a raw string.  Useful  for  escaping  a
144         password that starts with the “hex:” prefix.
145
146       · hex: - Used when specifying a password in hex string format.
147

PCR Bank Specfiers

149       PCR Bank Selection lists follow the below specification:
150
151              <BANK>:<PCR>[,<PCR>]
152
153       multiple banks may be separated by `+'.
154
155       For example:
156
157              sha:3,4+sha256:5,6
158
159       will  select  PCRs  3 and 4 from the SHA bank and PCRs 5 and 6 from the
160       SHA256 bank.
161
162   Note
163       PCR Selections allow for up to 5 hash to pcr selection mappings.   This
164       is  a  limitaion in design in the single call to the tpm to get the pcr
165       values.
166

EXAMPLES

168              tpm2_unseal -H 0x81010001 -P abc123 -o out.dat
169              tpm2_unseal -c item.context -P abc123 -o out.dat
170              tpm2_unseal -H 0x81010001 -P "hex:123abc" -o out.dat
171              tpm2_unseal -c item.context -L sha1:0,1,2 -F out.dat
172

RETURNS

174       0 on success or 1 on failure.
175

BUGS

177       Github Issues (https://github.com/01org/tpm2-tools/issues)
178

HELP

180       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
181
182
183
184tpm2-tools                      SEPTEMBER 2017                  tpm2_unseal(1)