From c3649a2def02c41d837ae1f79dda729ccb91e677 Mon Sep 17 00:00:00 2001 From: Igor Pashev Date: Sun, 25 Nov 2012 14:36:20 +0000 Subject: Imported Upstream version 0.3.9 --- README | 229 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 229 insertions(+) create mode 100644 README (limited to 'README') 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 + +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 -- cgit v1.2.3