IAIK/OpenTC PrivacyCA documentation

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

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.

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!

IAIK/OpenTC PrivacyCA is using a dual licensing model:

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.

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:

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

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.

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.

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.

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.

The certificates are:

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

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.

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:

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

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:

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.

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.

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

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.

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

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

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.

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

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:

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.

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.

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.

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.

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

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.

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.