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

IAIK XKMS is an implementation of the XML Key Management Specification protocol (XKMS). XKMS is one of the candidates for a PKI protocol serving a Trusted Computing infrastructure, as suggested by the TCG in their Reference Architecture for Interoperability (IWG) document:

  "XKMS provides a way to express certificate management function is XML,
   while providing a wrapper over legacy CA services designed for X.509
   certificates. As such, XKMS provides the most attractive solution for
   credential management for existing CAs in the PKI industry. XKMS has
   completed standardization in the W3C."

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

Development of IAIK XKMS is supported by the European Commission as part of the 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 goal of OpenTC is to reduce system-related threats, errors and malfunctions. The lack of platform security in today's computers has given rise to waves of successful attacks, resulting in severe damages to enterprises and potential failure of critical infrastructures.

The OpenTC consortium will define and implement 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 IAIK XKMS is experimental software. The use of IAIK XKMS in a real production environment is discouraged. No guarantees for data produced by IAIK XKMS can be made. Use the software at your own risk!

1.3. License

IAIK XKMS is currently released as a binary .jar archive, without source.

It can be used for educational, research use and evaluation free of charge.

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

It is assumed you already have some basic knowledge about public key infrastructures. If you want to learn more about this topic, this readme will not help you. Thanks for your understanding.

2.1. Current Status

IAIK XKMS is an almost complete implementation of the XKMS 2.0 specification. All request and response messages are implemented. Full support for message XML signatures and encryption is provided. Formal validation of message to XKMS schema is done, as well as checking if message contents are reasonable according to XKMS Assertions.
Basic HTTP-plain, SOAP11 and SOAP12 transport helpers are available.

Selected cases of "unbounded" or "anyType" as theoretically allowed by the XML schemata are not supported, either because of current implementation limitations, API limitation or no demonstrated practical application.

Note that IAIK XKMS is work in progress. There are bugs/issues.
API and functionality is expected to change in future builds.

The current build of IAIK XKMS does not contain functionality specific to Trusted Computing. This early build is released with the intention to test and improve compatibility with other XKMS implementations.

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

2.2. Requirements

Some items are optional, depending on how much of the IAIK XKMS functionality you want to use and/or which libraries you prefer:

• If you need certificate handling or crypto functions you need IAIK-JCE.

• If you need XML signatures you need IAIK-XSECT or JWSDP.

• If you need XML signatures and XML encryption (PrivateKey elements) choose IAIK-XSECT and not JWSDP.

• If you need SASLprep string preprocessing download libIDN.

If you download all libraries, your XKMS support libraries collection looks about like this:

lib/iaik_jce.jar
lib/iaik_xsect.jar
lib/libidn.jar
lib/xmldsig.jar
lib/xmlsec.jar
lib/jaxb/activation.jar
lib/jaxb/jaxb-api.jar
lib/jaxb/jaxb-impl.jar
lib/jaxb/jsr173_1.0_api.jar

2.2.1. Java 1.5

Development of IAIK XKMS was done using Sun JDK 1.5. A minimum of Java 5 platform is required as the code uses features like annotations, enums and generics. Compatibility with alternative Java vendors is unknown.

Compatibility with Java 6 in combination with XSECT should work from v0.2a onwards. Compatibility with alternative XML digital signature libraries is unknown/untested.

Note: For cryptographic operations with long keys "unlimited strength encryption" has to be enabled. For more information refer to JCE policy. (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.)

2.2.2. JAXB 2.0

For XML read/write the Java Architecture for XML Binding (JAXB) is needed. Development of IAIK XKMS was done with JAXB 2.03. JAXB is free for download at JAXB headquarters. Required libraries from JAXB are: activation.jar, jaxb-api.jar, jaxb-impl.jar and jsr173_1.0_api.jar.

2.2.3. IAIK-XSECT 1.04

IAIK-XSECT implements full support for XML Digital Signatures (JSR105) and XML Digital Encryption API (JSR106). This package is available as a free evaluation download from SIC.

2.2.4. IAIK-JCE 3.142

IAIK-JCE supplements features of the default JCE with required crypto functionality for IAIK XKMS. This package is available as a free evaluation download from SIC. If you already downloaded the XSECT evaluation version, JCE is included in /lib/signed/iaik_jce.jar.

2.2.5. JWSDP 2.0

Java Web Services Developer Pack (JWSDP) contains libraries supporting the XML Digital Signatures API according to JSR105. Download JWSDP 2.0 from JWSDP homepage
The required libraries are /xmldsig/lib/xmldsig.jar and /jwsdp-shared/lib/xmlsec.jar.

2.2.6. GNU libIDN 0.6.8

For SASLprep preprocessing of complex password strings GNU libIDN may be employed. Download from libIDN homepage.

The original build of libIDN does not contain SASLprep (RFC4013) support for Java. In subdirectory /libidnpatch of the IAIK XKMS distribution you can find a small patch. Follow the README in the same directory to generate a libIDN containing SASLprep support. This patch is for free distribution, "do whatever you like" with it.

Note that IAIK XKMS includes autodetection for SASLprep support, it will use it automatically if available in classpath. To manually check support, write a small test program calling:
System.out.println(iaik.xkms.Secret.getSASLprepSupport());

3.1. Commandline Demonstration Client

See directory /examples.

Included in the IAIK XKMS package is a very basic commandline client, allowing some interaction with an XKMS server without writing a single line of Java code.

There are 3 script variants:

client-iaik.sh
client-jwsdp-jce.sh
client-jwsdp.sh

The first one uses IAIK-JCE and IAIK-XSECT (offering full IAIK XKMS functionality), the second IAIK-JCE and JWSDP (limited functionality) and the third just JWSDP (basic functionality) as support libraries.

Edit (the top of) the specific script to point to your libraries.

Call the commandline client without parameters to obtain a list of available commands, e.g.:

./client-iaik.sh

***   IAIK XKMS commandline demonstration client   ***
***  (C) 2006 IAIK, Graz University of Technology  ***

available sub-commands:

  checkxml        ... check XML schema validity and consistency of values
  extractkey      ... extract PrivateKey of a result message
  locaterequest   ... LocateRequest
  recoverrequest  ... RecoverRequest
  registerrequest ... RegisterRequest
  reissuerequest  ... ReissueRequest
  revokerequest   ... RevokeRequest
  validate        ... validate signatures of a message
  validaterequest ... ValidateRequest

No sub-command given.

Specify a command to get a list of supported command options, e.g.:

./client-iaik.sh locaterequest

required parameters:
  --service       uri               ... specify service URI

optional parameters:
  --cert          file1,file2,...   ... specify KeyInfo X509Certificate
  --createonly                      ... only create message, dump to console
                                        and exit
[.....]
  --usekeywith2   "app ident"       ... add another UseKeyWith
  --value         pubkey            ... specify KeyInfo public key


Parameter Error: The required parameter '--service' was not set.

If, for example, you want to locate the data of alice@example.com at the XKMS test server provided by markupsecurity.com, you may write (all in one line):

./client-iaik.sh locaterequest --text
--service http://markupsecurity.com:4080/xkms/service/soap11 --envelope SOAP11
--respondwith KeyName,KeyValue,X509Chain --keyusage Encryption
--usekeywith "SMIME alice@example.com"

Study the available options for the parameters and dumping of result options.

The commandline client further includes 3 commands useful for debugging XKMS messages:

3.1.1. checkxml command

The "checkxml" command inspects a plain XML file and checks it for XKMS conformance. This is done in 2 steps: 1) Upon message import the XML input file is validated to the XKMS schema. 2) Upon message export the message content is checked if it is reasonable according to the XKMS assertions.

Included examples:

./client-iaik.sh checkxml --file checkxml-valid.xml
importing...
exporting...
..looks ok!

Compare to:

./client-iaik.sh checkxml --file checkxml-invalid.xml
importing...
cvc-complex-type.2.4.a: Invalid content was found starting with element
'Signature'. One of '{"http://www.w3.org/2002/03/xkms#":ResponseMechanism,
"http://www.w3.org/2002/03/xkms#":RespondWith,
"http://www.w3.org/2002/03/xkms#":PendingNotification,
"http://www.w3.org/2002/03/xkms#":PrototypeKeyBinding}' is expected.
unmarshalling failed

Or detecting suspicious XKMS content:

./client-iaik.sh checkxml --file checkxml-badcontent.xml
importing...
exporting...
Empty result with ResultMajor 'Success' which does not specify
'NoMatch' as ResultMinor

3.1.2. extractkey command

The "extractkey" command can extract and decrypt a PrivateKey block from a RegisterResult or RecoverResult message, e.g.:

./client-iaik.sh extractkey --file extractkey-aes256.xml --algo AES256
--code "e9708f10-a0314e3d-173a2026-3c1323e6-f445d7fa" --keyfile privatekey.der

AES key: 40471547f41f74e73a8544a91a5c5e57e67301b706e1c7996ea269aa9100ecf8
Decryption ok, key exported.

In case of wrong code:

./client-iaik.sh extractkey --file extractkey-aes256.xml --algo AES256 --code "whatever"

AES key: 611f00f52d38f2eb8f007fdead41226c9f511dd441fb7c9c5445025d00907823
Decryption failed

Note that extractkey only works with IAIK-JCE and IAIK-XSECT as support libraries. For strong keys (e.g. AES256) also don't forget to install the "unlimited strength encryption" policy files, see requirements chapter.

3.1.3. validate command

The "validate" command may be used to examine XKMS signatures. Global message signature, Authentication and ProofOfPossession signature.

Create a minimal demo RegisterRequest with all possible signatures (using private key from previous example):

./client-iaik.sh registerrequest --createonly --text --name SomeKeyName
--service http://example.com --signcert certificate.der
--signkey "privatekey.der e9708f10-a0314e3d-173a2026-3c1323e6-f445d7fa"
--pop "privatekey.der e9708f10-a0314e3d-173a2026-3c1323e6-f445d7fa"
--authcode secretcode >test.xml

Check them with validate:

./client-iaik.sh validate --file test.xml --authcode secretcode --pop certificate.der

ProofOfPossession signature is valid
Authentication signature is valid
Message global signature is valid (using public key from enclosed certificate)

Note that signatures are fragile entities. Reformatting/indenting with xmllint will break them. Just reading a message with IAIK XKMS and writing it out again will break the signature. Be careful with SOAP and other wrappings.

3.2. Testsuite

Directory /testsuite contains a setup to run the commandline client with testcases roughly resembling the official XKMS KISS und KRSS test collection.

runtest.rb is the main script for running a test, written in Ruby.
Directories /keyset and /cases contain the data files.

Almost all tests can run against the public XKMS test server of Tommy Lindberg at markupsecurity.com.
Tommy Lindberg kindly gave permission to include these examples for usage with his public markupsecurity test server - thank you!

Edit path on top of runtest.rb to point to your library set.

Run e.g.:

./runtest.rb markup-plain getchain-alice --output alicedata --progress

Sr
===>http://www.w3.org/2002/03/xkms#Success

With all output data pieces dumped into alicedata.* files.

Note that this tests cannot be run one after the other from first to last. Study the official XKMS tests and tweak the examples to your current setup and/or needs.

4.1. Javadoc

IAIK XKMS includes Javadoc documentation in the /doc/apidoc directory. Documentation is only provided for the toplevel classes which are intended for library usage.

[xyz] text markings are references to paragraphs in the original XKMS W3C specification.

Further, IAIK XKMS includes for convenience and offline execution the XKMS, XML digital signature, XML encryption and required base XML schemata.

For W3C copyright policies please see W3C copyright docs and W3C copyright software.

4.2. Library usage

Usage of IAIK XKMS as a library should be pretty straightforward. The API was designed to offer a convenient highlevel abstraction, shielding a client from lowlevel details like marshalling and XML digital signatures.

The starting point is XKMSContext.
From there, just follow the Javadoc :-)

Included in /examples is LocateExample.java, showing how to locate data (=LocateRequest) associated to alice@example.com at the markupsecurity.com testserver.

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