Trusted Computing for the Java(tm) Platform  

1. Introduction

Trusted Computing, as specified by the Trusted Computing Group (TCG), comprises multiple layers of hard- and software. While the hardware primarily consists of the Trusted Platform Module (TPM), there are multiple support software components required.

There are potential security benefits in connecting many trusted computing enabled platforms. However, there is a need to standardize security credentials to enable easy automated processing and the building of a trusted computing aware public key infrastructure (PKI).

One of the components in a secure network setup is a Public-Key Infrastructure (PKI). The adoption of Trusted Computing technologies demands an enhancement of existing PKI infrastructures as well as an adaption of procedures within PKIs. The specifications of the Trusted Computing Group TCG outline new type of credentials as well suggest ways to deploy them in practice.

This package is part of the effort to bring specifications to practical application. A basic prototype implementation of a PrivacyCA setup provides experience of the problems involved and leads the way for advanced services and integration.

The IAIK/OpenTC PrivacyCA is developed and maintained at the Institute for Applied Information Processing and Communication (Institut für Angewandte Informationsverarbeitung und Kommunikation (IAIK)), at Graz University of Technology (TU Graz).

1.1. OpenTC Project

The development of this package was supported by the European Commission as part of the FP7 OpenTC project (Ref. Nr. 027635).

The Open Trusted Computing (OpenTC) consortium is an R&D project focusing on the development of trusted and secure computing systems based on open source software. The project targets traditional computer platforms as well as embedded systems such as mobile phones.

The OpenTC consortium defines and implements an open Trusted Computing framework. The architecture is based on security mechanisms provided by low level operating system layers with isolation properties and interfaces to Trusted Computing hardware. These layers make it possible to leverage enhanced trust and security properties of the platform for standard operating systems, middleware and applications.

For more information about the OpenTC project please refer to the OpenTC homepage.

1.2. Word of Caution

Please keep in mind that this package is experimental software targeted at researchers and early adopters. It is a proof of concept prototype and not for use in a real production environment. Use the software at your own risk!

1.3. License

IAIK/OpenTC PrivacyCA is using a dual licensing model:

  • For Open Source development, the IAIK/OpenTC PrivacyCA is licensed under the terms of the GNU GPL version 2. The full text of the GNU GPL v2 is included in the package or can be found online at (GPL).

  • In all other cases, please contact jce-sales@iaik.at with your intended usage for further information.

2. Installation & Configuration

It is assumed that you already have some basic knowledge about public key infrastructures and the Trusted Computing PrivacyCA concept as envisioned by the Trusted Computing Group. If you want to learn more about this topics, this readme will not help you. Thank you for your understanding.

2.1. Overview

This package is a basic implementation of a PrivacyCA server, including commandline clients for demonstration of usage. The server side is implemented in Java while the clients are available for both Java and C.

For ease of distribution all components are packaged as one big archive. Depending on specific use the package can be split up as needed. Note that some paths are hardwired in the code, so upon renaming directories some code or script changes may be necessary.

The available commands can be summarized from the output of the Java client:

***   TC apki commandline demonstration client   ***
*** (C) 2009 IAIK, Graz University of Technology ***

available sub-commands:
  version         ... query library builds
  read_pubek      ... read public EK of TPM
  ekcert_create   ... read public EK and create EK certificate, using APKI protocol
  ekcert_validate ... validate EK certificate, using APKI protocol
  local_aik       ... simulate local PCA cycle
  aik_create      ... create AIK certificate, using APKI protocol
  aik_validate    ... validate AIK certificate, using APKI protocol
  aik_locate      ... locate AIK certificate, using APKI protocol
  aik_revoke      ... revoke AIK certificate, using APKI protocol
  tcb_quote       ... request quote of server state, using APKI protocol

2.2. PrivacyCA server

The PrivacyCA server is a standalone component which binds to a local network port and awaits connections.

2.2.1. Software Requirements

Software requirements comprise the Java runtime language itself as well as Java support libraries. The following two sections describe how to obtain and install this external dependencies.

Java

The development of this package was done using Sun Java 6. Compatibility with alternative Java vendors is unknown. We assume Java 5 can also be used, however, this has not been tested.

For the cryptographic operations with long keys "unlimited strength encryption" must be enabled in your Java disribution. For more information about installation refer to the Sun Java website (If you see an error message like "Illegal key size or default parameters" this is an indication that unlimited strength encryption is not enabled on your system).

This package was/is developed in a Linux environment. Alternative OS are currently untested/unsupported, but are expected to work equally well due to the portable nature of Java.

Support Libraries
  • IAIK-JCE: IAIK-JCE supplements features of the default JCE with required crypto and certificate functionalities.
    (iaik_jce.jar)

  • TCcert: TCcert implements Trusted Computing specific certificates.
    (iaik_tccert.jar)

  • jTSS: The Java TSS is a TCG Software Stack (TSS) implementation in pure Java. It allows Java software to directly access the TPM device. A minimum of jTSS version 0.4a is required!
    (iaik_jtss_tsp.jar, iaik_jtss_tcs.jar)

IAIK-JCE is available as a free evaluation download from SIC. TCcert and jTSS can be downloaded from TrustedJava@SF. Install all libraries in the /lib subdirectory of this package. The directory contains symlink placeholders for the 4 required .jar files. Replace the links, rename them or copy in the files - as you like. Also, in /lib you find a placeholder jtss_tsp.ini for the configuration of the jTSS. Overwrite it with a proper configuration for your system.

2.2.2. Certificates

The PrivacyCA expects a certain set of certificates to be available upon startup. The distribution package already contains the directory structure and placeholder files for your convenience. Just replace the files piece by piece with "your" certificates. Note that some paths are hardwired, so upon renaming or moving files changes to code or scripts may be necessary.

Note: This is a hierarchy/setup intended for quick experimentation and does not reflect a setup one would employ for a production system.

CA certificates

The certificates are:

A self signed CA root certificate

ca.cert

At the next level intermediate CA certificates + private keys for each service:

TPM Endorsement Key (EK) CA

caek.cert and caek.pkey

Attestation Identity Key (AIK) CA

caaik.cert and caaik.pkey

For the AIK creation cycle in Trusted Computing a PrivacyCA entity with distinct credentials is needed. These are represented by pca.cert, a certificate holding the public key to encrypt AIK requests with, and pca.pkey, containing the private key for decryption of requests.

All certificates are expected to be in /resources/certs at startup. To create this certificates, edit /resources/democerts.ini to your needs, delete existing files if necessary and then run build-democerts.sh in the same directory.

Infineon TPM Certificates

The PrivacyCA server only validates EK certificates from known issuers. EK certificates issued by this PrivacyCA are recognized automatically. Additionally, if you want to accept AIK requests from clients equipped with Infineon TPMs, the proper certificate chains for Infineon EK validation are required to be preloaded. The original files are available from the Infineon homepage.

For reference, the MD5sums of the files:

53a08af4ba673eefe5c06a5cb827d868  IFX-EK11root.cer
0186d0132ed08895106fd60f0cd2b6cb  IFX-EK12root.cer
b2173ec5de0751e8ea193e584d1f3e3b  IFX-EK12veriroot.cer
a3be9daa043b25061f023a5adcc06269  IFX_TPM_EK_Intermediate_CA_01.crt
f14715123140847beb67c371f9226f70  IFX_TPM_EK_Intermediate_CA_02.crt
578146d9a25c8a5d3f31bbe0b7817c96  IFX_TPM_EK_Intermediate_CA_03.crt

Note that Infineon 1.1 TPMs on early development boards require different certificate chains - unfortunately these are not publicly available.

2.2.3. Configuration

In the resources directory there is a server.config configuration file. Not all parameters are available in the config file yet and are still hardwired in the source code. However, the most important ones are. The structure of the config file should be self-explanatory, as it resembles a Java properties file.

Interesting options in common section:

port = 12345

Local port to bind server listener to

credentials = /path/somewhere

Specifies directory where to import certificates and private keys from

ekcertificate = file1, ekprivatekey = file2, ekprivatekeypassword = passwd

Certificate and private key for the TPM Endorsement Key certification authority, for the createEK functionality

aikcertificate = file1, aikprivatekey = file2, aikprivatekeypassword = passwd

Certificate and private key for the AIK certification authority, for the createAIK functionality

privacycacertificate = file1, privacycaprivatekey = file2, privacycapassword = passwd

Certificate and private key for the PrivacyCA entity, for AIK crypto cycle with TPM

preload = file1 file2

Specifies certification autorities certificates for preload for the validation module

Self-attestation support

The server supports reporting a self-attestation of the system state using the TPM. For this command an AIK is needed to sign the TPM quote with. The directory /quotedata must provide a quote.cert AIK certificate and an associated quote.key AIK key blob. The distribution package provides 0 byte sized placeholder-files for your convenience. Read the quote.txt files in the same directory on how to obtain the other two files for the tcb_quote command. You can only do this after you have set up the rest of this package and are familiar with the clients.

2.2.4. Run

Run the server.sh script to start the PrivacyCA. Note that you have to change your current working directory to this directory before calling this script. Console output provides some (debugging) information on what is happening.

2.3. PrivacyCA Java client

The PrivacyCA Java client is a simple commandline client which allows to interact with a remote PrivacyCA service.

2.3.1. Software Requirements

The Java commandline client requires the same software packages as the PrivacyCA server (see previous chapter). The client also requires access to the certificate of the PrivacyCA.

2.3.2. Execution

Run the client.sh script to start the Java commandline demo client.

2.4. PrivacyCA C client

The PrivacyCA Java client is a simple commandline client which allows to interact with a remote PrivacyCA service.

2.4.1. Software Requirements

TrouSerS: TrouSerS is a TCG Software Stack (TSS) implementation in C. It is available for download from Sourceforge. The official release currently is 0.3.1, however this version is already from Nov 2007(!). Use a recent (Feb 2009) CVS snapshot - which contains some important bug fixes.

The C client is not included as binary executable in this package, it must be compiled from source. For this you need a full TrouSerS installation, including all development headers. TrouSers implicitly requires OpenSSL for cryptography support. Don’t forget to install the development packages for OpenSSL also if they are not provided by your Linux distribution by default. Compile the C client by running make in the /srcc directory.

The client also requires access to the certificate of the PrivacyCA.

2.4.2. Execution

Run the cclient binary in the srcc subdirectory to start the C commandline demo client.

3. Development Documentation

This section details some low level technical details of this package. This information helps in rebuilding all the components of this package or to understand and expand its functionality, if desired.

The directory layout is as follows:

/certstore

Certificate storage directory for server side

/common

Command line and wire protocol interface Ragel definition files

/lib

Java support .jar libraries

/quotedata

Server key for self-attestation (tcb_quote command)

/resources

Configuration file and certificates for validation

/scripts

Development scripts for protocol generation

/src

Java sources (client + server)

/srcc

C sources

3.1. Compilation

3.1.1. Java

The build.xml configuration file for Ant in the root directory provides a jar target to rebuild the iaik_apki.jar required by the client.sh and server.sh scripts which start the Java client or server respectively. If the iaik_apki.jar file is missing, note that the shell scripts also include a /classes directory - thus this should be your output directory for develepment with an IDE.

3.1.2. C client

The source is located in /srcc with an appropriate Makefile. Upon first call to make the dependencies are generated and a warning is emitted - this is normal.

3.2. State machine regeneration

This PrivacyCA uses automatic code generation of state machines, which define the interface on the command line as well as the network protocol. This enforces protocol consistency between client and server, and commandline consistency between Java and C client implementation.

The tool used for this is the Ragel state machine compiler. The implementation language independent definitions are located in the /common directory. These are pure Ragel .rl files. For Java the associated files are src/iaik/tc/apki/client/CmdParser.rl and src/iaik/tc/apki/common/PkiParser.rl. For C these are srcc/cmd_parser.rl and srcc/pki_parser.rl.

In order to generate from the Ragel .rl into Java and C, change into the /scripts directory and run the ragel_c.sh and ragel_java.sh scripts. With help from two additional Ruby scripts these two sychronize changes made in the .rl and .c/.java files. E.g. edit your Java code in an IDE like Eclipse, save and run ragel_java.sh, and press F5 in Eclipse to refresh. Alternatively, edit an .rl, save and run the scripts to propagate the changes to the .java files, and refresh in your IDE again. Please read the source code and script comments for a more detailed description.

3.3. TPM access

Access to the TPM device /dev/tpm is needed on the client side by all commands except tcb_quote. At the server side no TPM access is needed, only by tcb_quote. From this follows you can run client and server for testing purposes on the same machine, you just have to be careful with the order of command invocation.

Further, the Java client can access the TPM directly via jTSS while the C client requires a running TrouSerS daemon. Testing simultaneously with Java and C clients thus requires (re)starting/stopping the TrouSerS daemon.

This package was designed to run with 1.2 TPMs. E.g. tcb_quote will not work with 1.1 TPMs due to structure differences in the PCR composite hash.

3.4. C client issues

The C client does not (yet) support all functions provided by the Java client. First, the jTSS provides more functionality than TrouSerS. Also, the Java TCcert library provides support not (yet) available in OpenSSL land.

  • The C client does not display the EK certificate Subject Alternative Name extension of TPM chip.

  • The C client does not display AIK certificate labels.

  • The C client does not read the EK directly from the TPM (if available). The EK certificate always needs to be passed in by --ekfile.

  • The C client does not support local_aik command.

  • The C client does not support tcb_quote command.

  • The C client does not yet implement different password encodings.

  • …..

3.5. PrivacyCA-in-a-Box

The PrivacyCA server and the network protocols are deliberately designed to be rather simple. This minimizes component dependencies and further the goals of security analysis and Trusted Computing understanding.

The companion guide to this package - "Build Guide for Bootstrapping a Reduced Trusted Java Compartment" - demonstrates an experimental approach on how to run the PrivacyCA server in a stripped down Linux+Java compartment - of only ~17 Mb size.

4. Support

For questions, bug reports, feature requests, patches, criticism and suggestions please use the following mailing list: trustedjava-support@lists.sourceforge.net.

TrustedJava@SF is the main project page for "Trusted Computing for Java" packages developed within OpenTC by IAIK.

5. Trademarks

Java and all Java based marks are a trademark or registered trademark of Sun Microsystems, Inc. in the United States and other countries. All other trademarks and copyrights are property of their respective owners.

6. Revision History

date version comment
2009/03/02 0.2 first public release