| _____ ____ __ __ _____ _ _ |
| |_ _| _ \| \/ | | ____|_ __ ___ _ _| | __ _| |_ ___ _ __ |
| | | | |_) | |\/| | _____ | _| | '_ ` _ \| | | | |/ _` | __/ _ \| '__| |
| | | | __/| | | | |_____| | |___| | | | | | |_| | | (_| | || (_) | | |
| |_| |_| |_| |_| |_____|_| |_| |_|\__,_|_|\__,_|\__\___/|_| |
| |
| 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> |
| |