Upgrade to tpm-emulator version 0.7.

README

  _____ ____  __  __           _____                 _       _
 |_   _|  _ \|  \/  |         | ____|_ __ ___  _   _| | __ _| |_ ___  _ __
   | | | |_) | |\/| |  _____  |  _| | '_ ` _ \| | | | |/ _` | __/ _ \| '__|
   | | |  __/| |  | | |_____| | |___| | | | | | |_| | | (_| | || (_) | |
   |_| |_|   |_|  |_|         |_____|_| |_| |_|\__,_|_|\__,_|\__\___/|_|
 
- TPM-Emulator v0.6 -
- A Software-based Trusted Platform Module (TPM) Emulator for Linux.
+ TPM-Emulator v0.7 -
+ A Software-based TPM and MTM Emulator.
 --------------------------------------------------------------------------
 
-$Id$
+$Id: README 424 2010-02-22 16:36:14Z mast $
 
 Copyright
 --------------------------------------------------------------------------
-Copyright (C) 2004-2006 Mario Strasser <mast@gmx.net> and Swiss Federal
-Institute of Technology (ETH) Zurich.
+Copyright (C) 2004-2010 Mario Strasser <mast@gmx.net>, ETH Zurich.
 
 This program is free software; you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation; either version 2 of the License, or
 (at your option) any later version.
 
 This program is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 
 Package
 --------------------------------------------------------------------------
-Since version 0.5, the tpm emulator package comprises four main parts:
+The tpm emulator package comprises four main parts:
 
-a) tpmd - a user-space daemon that implements the actual TPM emulator
-   and can be accessed by means of unix domain sockets.
+a) tpmd - a user-space application that implements the actual emulator
+   and can be accessed by means of Unix domain sockets (Unix) or
+   named pipes (Windows).
 
 b) tpmd_dev - a kernel module that provides the device /dev/tpm for
-   backward compatibility and forwards the received commands to tpmd.
+   backward compatibility and forwards the received commands to tpmd
+   (Unix and Mac OS X only).
 
-c) tddl - a TSS conform device driver library for the TPM emulator.
+c) tddl - a TSS conform device driver library for the emulator.
 
-d) tpm_dev - the (obsolete) kernel-space TPM emulator.
-
-
-Configuration
---------------------------------------------------------------------------
-First of all, you have to make sure that the GNU MP library (http://
-www.gnu.org/software/gmp/gmp.html) is properly installed on your system;
-in particular that the required shared library and header files exist
-and are located within the search path of the compiler and linker.
-
-The compilation and installation process of the kernel modules uses the
-build environment for external kernel modules of the 2.5.X Linux kernels,
-which must therefore be set up properly. If you are using a pre-compiled
-standard kernel of some distribution, install the appropriate kernel-source
-packages and call the following commands:
-
-# cd /usr/src/linux
-# zcat /proc/config.gz > .config
-# make oldconfig
-# make modules_prepare
 
 Compilation and Installation
 --------------------------------------------------------------------------
-The actual compilation and installation of the TPM emulator package is
-done as follows:
+The compilation and installation of the TPM emulator package is based on
+the CMake build environment (version 2.6 or better) and requires that the 
+GNU MP library (version 4.0 or better) is properly installed on your
+system. A working MinGW compiler suite is further required on Windows
+(see http://www.mingw.org/). To compile and install the package execute:
 
 # tar -xvzf tpm_emulator-X.Y.tar.gz
 # cd tpm_emulator-X.Y
+# mkdir build
+# cd build
+# cmake ../
 # make
 # make install
 
-Please note that the user and group 'tss' must exists on the target host.
+The script files build.sh and build.bat automate this process.
+
+On Windows, the TPM emulator system service has additionally to be
+registered by calling:
+# control_tpmd.bat install
+
+MTM support can be enabled by replacing
+# cmake ../
+with
+# cmake ../ -DMTM_EMULATOR=ON
 
 
 Startup
 --------------------------------------------------------------------------
-In order to use the TPM emulator, one has to start the TPM emulator daemon
-and, if required, load the TPM device forwarding module. The startup mode
-of the TPM (see TPM Spec. Part 1) is defined by the startup mode argument
-and can either be set to clear, save (default) or deactivated.
+In order to use the TPM emulator on Unix or Mac OS X, one has to start the
+TPM emulator daemon and load the TPM device forwarding module. On Linux,
+this is done by executing:
 
 # modprobe tpmd_dev
-# tpmd save
+# tpmd
 
-Furthermore, the argument -d enables debug mode, -f forces the emulator
-to run in the foreground, and -h print the following help message:
+On Windows, the TPM emulator service can either be started with the
+Microsoft Management Console or with the control_tpmd.bat script:
 
-usage: tpmd/tpmd [-d] [-f] [-h] [startup mode]
+# control_tpmd.bat start
+# control_tpmd.bat status
+
+The startup mode of the TPM (see TPM Spec. Part 1) is defined by the
+startup mode argument and can either be set to clear, save (default)
+or deactivated. Additionally supported arguments are
+
+usage: tpmd [-d] [-f] [-s storage file] [-u unix socket name]
+            [-o user name] [-g group name] [-h] [startup mode]
   d : enable debug mode
   f : forces the application to run in the foreground
+  s : storage file to use (default: /var/lib/tpm/tpm_emulator-1_2_0_7)
+  u : unix socket name to use (default: /var/run/tpm/tpmd_socket:0)
+  o : effective user the application should run as
+  g : effective group the application should run as
   h : print this help message
   startup mode : must be 'clear', 'save' (default) or 'deactivated
 
+and
+
+usage: tpmd.exe [-d] [-f] [-s storage file] [-u windows pipe name]
+                [-l log file] [-h] [startup mode]
+  d : enable debug mode
+  f : forces the application to run in the foreground
+  s : storage file to use (default:
+      C:/Program Files/TPM_Emulator/tpm_emulator-1_2_0_7)
+  u : windows named pipe name to use (default: //./pipe/tpmd:0)
+  l : name of the log file (default: C:/Program Files/TPM_Emulator/tpmd.log)
+  h : print this help message
+  startup mode : must be 'clear', 'save' (default) or 'deactivated
+
+on Unix and Windows, respectively.
+
 If the emulator is started in mode save and fails to load a previously
 stored TPM state, it will go into fail-stop mode and has to be reloaded.
 Therefore, the first time the TPM emulator is started, the argument must
 be set to 'clear'. Recovering a TPM emulator that is in fail-stop mode
 is done by first deactivating it and then reloading it in mode 'clear':
 
 # tpmd deactivated
 # killall tpmd
 # tpmd clear
 
 
 Usage and Backward Compatibility
 --------------------------------------------------------------------------
 The most correct and convenient way to access the tpm emulator is to use
 the provided device driver library (tddl). For a comprehensive description
 of its functionality we refer to the official TCG specification (see
 https://www.trustedcomputinggroup.org/specs/TSS), an example of use is
 given by the test application tddl/test_tddl.
 
-For backward compatibility with existing applications, the kernel module
-tpmd_dev forwards any command sent to the device /dev/tpm to the tpm
-emulator daemon. In order to access the emulator directly (i.e., without
-using the device driver library or the device dev/tpm) all one has to do
-is to include the header files sys/socket.h and sys/un.h and to replace
-the open("/dev/tpm") call with something like:
+Note that on Windows the tddl is called ifxtpm.dll as many applications
+(e.g., TPM/J) expect this name and do not support alternative drivers.
+
+For backward compatibility with existing Unix applications, the kernel
+module tpmd_dev forwards any command sent to the device /dev/tpm to the
+tpm emulator daemon. In order to access the emulator directly (i.e.,
+without using the device driver library or the device dev/tpm) all one
+has to do is to include the header files sys/socket.h and sys/un.h and
+to replace the open("/dev/tpm") call with something like:
 
 struct sockaddr_un addr;
 fh = socket(PF_UNIX, SOCK_STREAM, 0);
 if (fh < 0) { /* handle error */ }
 addr.sun_family = AF_UNIX;
 strncpy(addr.sun_path, "/var/run/tpm/tpmd_socket:0", sizeof(addr.sun_path));
 res = connect(fh, (struct sockaddr*)&addr, sizeof(struct sockaddr_un));
 if (res < 0) { /* handle error */ }
 
 All subsequent calls of read(), write(), and close() should work as
 expected.
 
 
+Usage Examples for TPM/J
+--------------------------------------------------------------------------
+
+=== Linux
+# modprobe tpmd_dev
+# tpmd -d
+
+# cd <path to tpmj>/lib
+# export CLASSPATH=tpmj.jar:bcprov-jdk15-131.jar:$CLASSPATH
+# java edu.mit.csail.tpmj.tools.TPMInfo
+
+
+=== Mac OS X
+# sudo kextload /System/Library/Extensions/tpm_bridge.kext
+# sudo tpmd -d
+
+# cd <path to tpmj>/lib
+# export CLASSPATH=tpmj.jar:bcprov-jdk15-131.jar:$CLASSPATH
+# sudo java edu.mit.csail.tpmj.tools.TPMInfo
+
+
+=== Windows
+# set PATH=%PROGRAMFILES%\TPM_Emulator;%PATH%
+# set PATH=%PROGRAMFILES%\TPM_Emulator\lib;%PATH%
+# control_tpmd.bat start
+
+# cd <path to tpmj>\lib
+# set CLASSPATH=tpmj.jar;bcprov-jdk15-131.jar:%CLASSPATH%
+# java edu.mit.csail.tpmj.tools.TPMInfo
+
+
 Notes
 --------------------------------------------------------------------------
+* Since release 0.7 the emulator also runs on Darwin (Mac OS X) and on
+  Windows; thanks go to Amit Singh and Domenic Schröder. In addition,
+  the emulator now also supports MTM emulation; thanks go to Jan-Erik
+  Ekberg and Markku Kylänpää from Nokia.
 * Since release 0.5.1 the emulator supports Free- and OpenBSD; thanks go
   to Sebastian Schuetz.
 * Since release 0.5 the kernel-based emulator (tpm_dev) is obsolete.
 * The name and format of the persistent-storage file has changed between
-  release 0.2 and 0.3 as well as between release 0.4 and 0.4.1.
+  release 0.2 and 0.3, 0.4 and 0.4.1., 0.5 and 0.6, and 0.6 and 0.7.
 * The DAA support was tested with the IBM DAA Test Suite and should work 
   now as expected. Thanks go to Roger Zimmermann for his kindly help.
 
 
 Contact
 --------------------------------------------------------------------------
 Any comments, suggestions and bug reports are welcome. Please, mention
 the keyword 'TPM emulator' in the subject.
 Mario Strasser <mast@gmx.net>