README

 _____ ____  __  __           _____                 _       _
|_   _|  _ \|  \/  |         | ____|_ __ ___  _   _| | __ _| |_ ___  _ __
  | | | |_) | |\/| |  _____  |  _| | '_ ` _ \| | | | |/ _` | __/ _ \| '__|
  | | |  __/| |  | | |_____| | |___| | | | | | |_| | | (_| | || (_) | |
  |_| |_|   |_|  |_|         |_____|_| |_| |_|\__,_|_|\__,_|\__\___/|_|

 TPM-Emulator v0.7 -
 A Software-based TPM and MTM Emulator.
--------------------------------------------------------------------------

$Id: README 424 2010-02-22 16:36:14Z mast $

Copyright
--------------------------------------------------------------------------
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
--------------------------------------------------------------------------
The tpm emulator package comprises four main parts:

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
   (Unix and Mac OS X only).

c) tddl - a TSS conform device driver library for the emulator.


Compilation and Installation
--------------------------------------------------------------------------
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

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 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

On Windows, the TPM emulator service can either be started with the
Microsoft Management Console or with the control_tpmd.bat script:

# 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.

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, 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>