1trousers README
2
3 Trousers is an open-source TCG Software Stack (TSS), released under
4the BSD License. Trousers aims to be compliant with the
51.1b and 1.2 TSS specifications available from the Trusted Computing
6Group website:
7
8http://www.trustedcomputinggroup.org
9
10
11CONTACT
12
13 For information on the TrouSerS project, please send mail to the
14following lists:
15
16Use of the TSS API and TrouSerS:
17 trousers-users@lists.sf.net
18
19Discussion of the internals of the TrouSerS implementation:
20 trousers-tech@lists.sf.net
21
22Possibly sensitive security related bugs:
23 Hon Ching(Vicky) Lo <honclo@linux.vnet.ibm.com>
24
25Run-of-the-mill bug reports should use the TrouSerS bug tracker:
26 http://sourceforge.net/tracker/?group_id=126012&atid=704358
27
28
29BUILD REQUIREMENTS
30
31 Packages needed to build:
32
33 automake > 1.4
34 autoconf > 1.4
35 pkgconfig
36 libtool
37 gtk2-devel
38 openssl-devel >= 0.9.7
39 pthreads library (glibc-devel)
40
41
42BUILDING the TSS 32-bit
43
44 Build and install the latest TPM device driver from
45sf.net/projects/tpmdd either compiled in or loaded as a
46module. UPDATE: This driver is now included in the vanilla 2.6.12
47kernel! If you are doing this, trousers should just work after a
48vanilla build. Follow the build instructions below and read
49RUNNING the TSS, below.
50
51 To build trousers after you have the device driver installed:
52
53 $ sh bootstrap.sh
54 $ ./configure [--enable-debug] [--enable-gprof] [--enable-gcov]
55 $ make
56 # make install
57
58 Here are the default locations of files that trousers installs:
59
60 /usr/local/sbin/tcsd
61 /usr/local/etc/tcsd.conf
62 /usr/local/lib/libtspi.so.0.0.X
63 /usr/local/lib/libtspi.so.0 -> libtspi.so.0.0.X
64 /usr/local/lib/libtspi.so -> libtspi.so.0.0.X
65 /usr/local/lib/libtspi.la
66 /usr/local/lib/libtddl.a
67 /usr/local/var/lib/tpm
68
69 By default the build will place everything in /usr/local. To install
70in a slightly more predictable place, use `./configure --prefix=/usr`.
71
72 'make install' will run ldconfig, but if /usr/local/lib is not in
73your /etc/ld.so.conf, this won't make a difference. You may need to
74manually add it and run ldconfig as root to allow your apps to link at
75run time to libtspi.so.
76
77
78BUILDING the TSS 64-bit
79
80 TrouSerS has been built and tested on ppc64 and x86_64, so please
81don't hesitate to report bugs on these platforms. Building everything
8264-bit will require a few more flags than are necessary for a 32-bit
83platform. Here are some example instructions for ppc64:
84
85 $ sh bootstrap.sh
86 $ export PKG_CONFIG_PATH=/usr/lib64/pkgconfig
87 $ CFLAGS="-L/usr/lib64 -L/opt/gnome/lib64" LDFLAGS="-L/usr/lib64 \
88 -L/opt/gnome/lib64" ./configure --libdir="/usr/local/lib64"
89 $ make
90 # make install
91
92 Hopefully the above example will get you going on building in your
9364-bit environment. If you need to do anything special, please send
94your build steps to trousers-users@lists.sf.net and I'll include it
95here.
96
97
98USING TROUSERS ON AN ALREADY OWNED TPM
99
100 If you've already taken ownership of your TPM using a TSS under another
101operating system, there are a few issues you should be aware of.
102
103 Auth vs No-Auth SRK: In order to trick trousers into thinking it has taken
104ownership of the TPM it's running on, you will need to create a persistent
105storage file for trousers to use. Normally trousers would create this file
106itself at the time ownership is taken. If your SRK has been given an
107authorization password by the non-Linux OS, you will need to move the file
108dist/system.data.auth to /usr/local/var/lib/tpm/system.data. If you've
109taken ownership of your TPM without issuing a password, move
110dist/system.data.noauth to /usr/local/var/lib/tpm/system.data.
111
112 Passwords: When entering passwords for keys you'd like to use in both
113Linux and other OS's, you'll need to take note of how you entered those
114passwords. The TSS spec states that when a password is entered through a
115GUI popup dialog box provided by the TSS library, the password should be
116converted to the UTF-16 encoding and then hashed using SHA-1, including
117the UTF-16 null terminator in the hash calculation.
118
119 In order to work around this problem, specify the -u option to the
120tpm-tools command line to convert the password to UTF-16 before hashing.
121This, however, unfolds yet another problem...
122
123 Some TSS stacks aren't compliant with the TSS spec, in that they hash
124their passwords without including the terminating null character. This
125means that there are effectively two versions of any password set through
126a popup dialog box. Trousers will include the terminating null character
127in its hashes of UTF-16 data.
128
129 We'll do our best to track other TSS software and how it behaves. Please
130see the trousers FAQ at http://trousers.sf.net for more information.
131
132
133ARCHITECTURE
134
135 This TSS implementation has several components.
136
137 A) The TCS Daemon - A user space daemon that should be (according to
138 the TSS spec) the only portal to the TPM device driver. At boot
139 time, the TCS Daemon should be started, it should open the TPM
140 device driver and from that point on, all requests to the TPM
141 should go through the TSS stack. The TCSD manages TPM resources
142 and handles requests from TSP's both local and remote.
143
144 B) The TSP shared library - The TSP (TCG Service Provider) is a
145 shared library that enables applications to talk to TCSD's both
146 locally and remotely. The TSP also manages resources used in
147 commicating with the application and the TCSD and transparently
148 contacts the TCSD whenever necessary.
149
150 C) Persistent Storage (PS) files - TSS's have 2 different kinds of
151 PS for keys. PS can be thought of as a database for keys, with
152 each key in the database indexed by a UUID.
153
154 'User' persistent storage is maintained by the application's TSP
155 library. Upon writing the first key to User PS, the TSP library
156 creates a new file at ~/.trousers/user.data, using the effective
157 user id of the process executing the call to find ~. An environment
158 variable, TSS_USER_PS_FILE, can also be set to point the TSP library
159 to a different location for the User PS. This environment variable
160 has the lifetime of the TSP context, so to store 2 keys in 2
161 different files, you will need to call Tspi_Context_Close, set the
162 new location, and open the context again.
163
164 'System' persistent storage is controlled by the TCS and stays
165 valid across all application lifetimes, TCSD restarts and system
166 resets. Data registered in system PS stays valid until an application
167 requests that it be removed. The System PS file by default is
168 /usr/local/var/lib/tpm/system.data. The system PS file is initially
169 created when ownership of the TPM is first taken.
170
171 D) A config file. By default located in /usr/local/etc/tcsd.conf.
172
173
174RUNNING the TSS
175
176 By default, the TCS daemon is not reachable over the internet, so if
177you just plan to access it locally, running it as root with a root owned
178device node is probably ok. Just make sure your device driver is loaded
179and start the tcsd as root.
180
181 If you would like to run the TCS daemon as an unprivleged user,
182please follow these instructions:
183
184 If you're using the device driver from a linux 2.6.12+ kernel and have
185udev enabled, you need to add the following line to your
186udev.permissions file (usually in /etc/udev somewhere):
187
188 tpm[0-9]:tss:tss:0600
189
190 and then just load the device driver with:
191 # modprobe tpm_atmel
192 or,
193 # modprobe tpm_natl
194
195 start the TCS Core Services daemon, by default /usr/local/sbin/tcsd.
196 # /usr/local/sbin/tcsd
197
198 If you're attempting to make the TCS Core Services daemon communicate with a
199softwware TPM through TCP, you must call it using the -e option.
200
201 # /usr/local/sbin/tcsd -e
202
203 The default values for hostname, port and UN socket device path are "localhost",
204"6545" and "/var/run/tpm/tpmd_socket:0". It will search for the IN socket device,
205then for an UN socket one, and then for the real TPM in this order.
206The default values match with the current open source project required values, if
207for instance case you need to set values of your choice, the environment variables
208for them are TCSD_TCP_DEVICE_HOSTNAME, TCSD_TCP_DEVICE_PORT if using an IN socket
209and TCSD_UN_SOCKET_DEVICE_PATH if running an UN socket.
210
211
212DEBUGGING
213
214 If you've compiled trousers with './configure --enable-debug' and would like
215to turn debugging output off at run-time, set the environment variable
216TSS_DEBUG_OFF to any value.
217
218
219BUILDING a TSS RPM
220
221 # sh bootstrap.sh
222 # ./configure
223 # cd ..
224 # mv trousers trousers-${version}
225 # tar zcvf /usr/src/packages/SOURCES/trousers-${version}.tar.gz \
226 trousers-${version}
227 # rpmbuild -bb trousers-${version}/dist/trousers.spec
228
229EOF
230