Imported Upstream version 0.3.9upstream/0.3.9upstream

1 files changed, 229 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..2a0ea10
--- /dev/null
+++ b/README
@@ -0,0 +1,229 @@
+trousers README
+
+  Trousers is an open-source TCG Software Stack (TSS), released under
+the Common Public License. Trousers aims to be compliant with the
+1.1b and 1.2 TSS specifications available from the Trusted Computing
+Group website:
+
+http://www.trustedcomputinggroup.org
+
+
+CONTACT
+
+  For information on the TrouSerS project, please send mail to the
+following lists:
+
+Use of the TSS API and TrouSerS:
+  trousers-users@lists.sf.net
+
+Discussion of the internals of the TrouSerS implementation:
+  trousers-tech@lists.sf.net
+
+Possibly sensitive security related bugs:
+  Debora Velarde <dvelarde@us.ibm.com>
+
+Run-of-the-mill bug reports should use the TrouSerS bug tracker:
+  http://sourceforge.net/tracker/?group_id=126012&atid=704358
+
+
+BUILD REQUIREMENTS
+
+  Packages needed to build:
+
+  automake > 1.4
+  autoconf > 1.4
+  pkgconfig
+  libtool
+  gtk2-devel
+  openssl-devel >= 0.9.7
+  pthreads library (glibc-devel)
+
+
+BUILDING the TSS 32-bit
+
+  Build and install the latest TPM device driver from
+sf.net/projects/tpmdd either compiled in or loaded as a
+module. UPDATE: This driver is now included in the vanilla 2.6.12
+kernel!  If you are doing this, trousers should just work after a
+vanilla build. Follow the build instructions below and read
+RUNNING the TSS, below.
+
+  To build trousers after you have the device driver installed:
+
+  $ sh bootstrap.sh
+  $ ./configure [--enable-debug] [--enable-gprof] [--enable-gcov]
+  $ make
+  # make install
+
+  Here are the default locations of files that trousers installs:
+
+  /usr/local/sbin/tcsd
+  /usr/local/etc/tcsd.conf
+  /usr/local/lib/libtspi.so.0.0.X
+  /usr/local/lib/libtspi.so.0 -> libtspi.so.0.0.X
+  /usr/local/lib/libtspi.so -> libtspi.so.0.0.X
+  /usr/local/lib/libtspi.la
+  /usr/local/lib/libtddl.a
+  /usr/local/var/lib/tpm
+
+  By default the build will place everything in /usr/local. To install
+in a slightly more predictable place, use `./configure --prefix=/usr`.
+
+  'make install' will run ldconfig, but if /usr/local/lib is not in
+your /etc/ld.so.conf, this won't make a difference. You may need to
+manually add it and run ldconfig as root to allow your apps to link at
+run time to libtspi.so.
+
+
+BUILDING the TSS 64-bit
+
+  TrouSerS has been built and tested on ppc64 and x86_64, so please
+don't hesitate to report bugs on these platforms.  Building everything
+64-bit will require a few more flags than are necessary for a 32-bit
+platform.  Here are some example instructions for ppc64:
+
+  $ sh bootstrap.sh
+  $ export PKG_CONFIG_PATH=/usr/lib64/pkgconfig
+  $ CFLAGS="-L/usr/lib64 -L/opt/gnome/lib64" LDFLAGS="-L/usr/lib64 \
+           -L/opt/gnome/lib64" ./configure --libdir="/usr/local/lib64"
+  $ make
+  # make install
+
+  Hopefully the above example will get you going on building in your
+64-bit environment.  If you need to do anything special, please send
+your build steps to trousers-users@lists.sf.net and I'll include it
+here.
+
+
+USING TROUSERS ON AN ALREADY OWNED TPM
+
+  If you've already taken ownership of your TPM using a TSS under another
+operating system, there are a few issues you should be aware of.
+
+  Auth vs No-Auth SRK:  In order to trick trousers into thinking it has taken
+ownership of the TPM it's running on, you will need to create a persistent
+storage file for trousers to use.  Normally trousers would create this file
+itself at the time ownership is taken.  If your SRK has been given an
+authorization password by the non-Linux OS, you will need to move the file
+dist/system.data.auth to /usr/local/var/lib/tpm/system.data.  If you've
+taken ownership of your TPM without issuing a password, move
+dist/system.data.noauth to /usr/local/var/lib/tpm/system.data.
+
+  Passwords:  When entering passwords for keys you'd like to use in both
+Linux and other OS's, you'll need to take note of how you entered those
+passwords.  The TSS spec states that when a password is entered through a
+GUI popup dialog box provided by the TSS library, the password should be
+converted to the UTF-16 encoding and then hashed using SHA-1, including
+the UTF-16 null terminator in the hash calculation.
+
+  In order to work around this problem, specify the -u option to the
+tpm-tools command line to convert the password to UTF-16 before hashing.
+This, however, unfolds yet another problem...
+
+  Some TSS stacks aren't compliant with the TSS spec, in that they hash
+their passwords without including the terminating null character.  This
+means that there are effectively two versions of any password set through
+a popup dialog box.  Trousers will include the terminating null character
+in its hashes of UTF-16 data.
+
+  We'll do our best to track other TSS software and how it behaves.  Please
+see the trousers FAQ at http://trousers.sf.net for more information.
+
+
+ARCHITECTURE
+
+  This TSS implementation has several components.
+
+  A) The TCS Daemon - A user space daemon that should be (according to
+     the TSS spec) the only portal to the TPM device driver. At boot
+     time, the TCS Daemon should be started, it should open the TPM
+     device driver and from that point on, all requests to the TPM
+     should go through the TSS stack. The TCSD manages TPM resources
+     and handles requests from TSP's both local and remote.
+
+  B) The TSP shared library - The TSP (TCG Service Provider) is a
+     shared library that enables applications to talk to TCSD's both
+     locally and remotely. The TSP also manages resources used in
+     commicating with the application and the TCSD and transparently
+     contacts the TCSD whenever necessary.
+
+  C) Persistent Storage (PS) files - TSS's have 2 different kinds of
+     PS for keys.  PS can be thought of as a database for keys, with
+     each key in the database indexed by a UUID.
+
+     'User' persistent storage is maintained by the application's TSP
+     library.  Upon writing the first key to User PS, the TSP library
+     creates a new file at ~/.trousers/user.data, using the effective
+     user id of the process executing the call to find ~. An environment
+     variable, TSS_USER_PS_FILE, can also be set to point the TSP library
+     to a different location for the User PS. This environment variable
+     has the lifetime of the TSP context, so to store 2 keys in 2
+     different files, you will need to call Tspi_Context_Close, set the
+     new location, and open the context again.
+
+     'System' persistent storage is controlled by the TCS and stays
+     valid across all application lifetimes, TCSD restarts and system
+     resets. Data registered in system PS stays valid until an application
+     requests that it be removed. The System PS file by default is
+     /usr/local/var/lib/tpm/system.data. The system PS file is initially
+     created when ownership of the TPM is first taken.
+
+  D) A config file. By default located in /usr/local/etc/tcsd.conf.
+
+
+RUNNING the TSS
+
+  By default, the TCS daemon is not reachable over the internet, so if
+you just plan to access it locally, running it as root with a root owned
+device node is probably ok.  Just make sure your device driver is loaded
+and start the tcsd as root.
+
+  If you would like to run the TCS daemon as an unprivleged user,
+please follow these instructions:
+
+  If you're using the device driver from a linux 2.6.12+ kernel and have
+udev enabled, you need to add the following line to your
+udev.permissions file (usually in /etc/udev somewhere):
+
+  tpm[0-9]:tss:tss:0600
+
+  and then just load the device driver with:
+  # modprobe tpm_atmel
+  or,
+  # modprobe tpm_natl
+
+  start the TCS Core Services daemon, by default /usr/local/sbin/tcsd.
+  # /usr/local/sbin/tcsd
+
+  If you're attempting to make the TCS Core Services daemon communicate with a
+softwware TPM through TCP, you must call it using the -e option. 
+
+  # /usr/local/sbin/tcsd -e
+
+  The default values for hostname, port and UN socket device path are  "localhost", 
+"6545" and "/var/run/tpm/tpmd_socket:0". It will search for the IN socket device,
+then for an UN socket one, and then for the real TPM in this order.
+The default values match with the current open source project required values, if
+for instance case you need to set values of your choice, the environment variables 
+for them are TCSD_TCP_DEVICE_HOSTNAME, TCSD_TCP_DEVICE_PORT if using an IN socket 
+and TCSD_UN_SOCKET_DEVICE_PATH if running an UN socket.
+
+
+DEBUGGING
+
+  If you've compiled trousers with './configure --enable-debug' and would like
+to turn debugging output off at run-time, set the environment variable
+TSS_DEBUG_OFF to any value.
+
+
+BUILDING a TSS RPM
+
+ # sh bootstrap.sh
+ # ./configure
+ # cd ..
+ # mv trousers trousers-${version}
+ # tar zcvf /usr/src/packages/SOURCES/trousers-${version}.tar.gz \
+            trousers-${version}
+ # rpmbuild -bb trousers-${version}/dist/trousers.spec
+
+EOF