Seal.

Java Maintainers Guide

This guide aims at the developer who will be maintaining or extending the Seal.Java library. It is not meant as an introduction to using the library in 3rd party products.

Page 1 / 10

Content
Changelog.............................................................................................................................................3 Configuring the build environment......................................................................................................3 Subversion........................................................................................................................................3 Directory Structure...........................................................................................................................3 Maven Goals.....................................................................................................................................4 How to get started with the Seal.java library.......................................................................................4 Installing and configuring a JDK.....................................................................................................4 Checking out the Seal.java from Subversion...................................................................................4 Installing Maven...............................................................................................................................4 The first build...................................................................................................................................4 How to configure the JDK....................................................................................................................5 SEAL 1.4+........................................................................................................................................5 Export Policy................................................................................................................................5 SEAL 1.0 - 1.3..................................................................................................................................5 Export Policy................................................................................................................................5 Configuring JCE with support for RSA...........................................................................................5 Bouncycastle Provider......................................................................................................................6 Installing an Eclipse project for the seal component............................................................................6 Configuring Eclipse..........................................................................................................................6 Installing the Subversion plugin for Eclipse....................................................................................6 Installing the Clover plugin for Eclipse............................................................................................6 Configuring code templates..............................................................................................................6 How to configure your subversion client.............................................................................................7 Configure Apache JMeter for load testing...........................................................................................7 Releasing the SOSI library...................................................................................................................7 Preparing the release.........................................................................................................................7 Making the release............................................................................................................................8 Testing the release............................................................................................................................8 Publishing the release.......................................................................................................................8 Q&A.....................................................................................................................................................8

Page 2 / 10

Changelog
Date 2007-2008 March 10, 2009 Change TWiki revision Microsoft Word Revision, minor updates Author JRI, CC KKJ

Configuring the build environment

Subversion
Soucecode, binary artifacts and all dependencies are found in Subversion at: https://svn.softwareborsen.dk/sosi. You can browse the sourcecode via web at http://svn.softwareborsen.dk/sosi or you can use an external Subversion client for instance: Product Tortoise SVN URL http://tortoisesvn.tigris.org OS Windows XP

Metissian Subversion http://metissian.com/projects/macosx/subversion Mac OS X Command Line You can also use a Subversion client embedded in your favorite development environment, for instance the Eclipse plugin that can be found at http://subclipse.tigris.org/

Directory Structure
The SOSI component Subversion structure is based on well known TTB (Trunk, Tags, Branches) structure. Under that the project contains some external tools (tomcat-xxx/, jmeter-xxx/), all packed releases (releases/), the project license (license/), configuration files (config/) and last but not least the source code (modules/). The directory structure is as follows:
* trunk - Head of repository * tomcat-xxx - Tool * jmeter-xxx - Tool * license - Project License * config - Tools config files * modules - Source code * seal - The SOSI component * src - Source folder * main - Application source * test - Test source * demo - Demo applications * idp - Demo Identity Provider * client - Demo SOSI web service client * provider - Demo SOSI web service provider * maven-jmeter-report-plugin - Maven plugin to generate jmeter report * ant-plugin - Maven plugin to handle Ant tasks * tags - Tags in repository * branches - Branches in repository * releases - Releases of Seal

Page 3 / 10

Maven Goals
The SOSI component is built with Apache Maven 2 which must be downloaded and installed. See this link for a how-to. The subprojects can be built separately and will automatically build dependencies, and download libraries etc. After installation you can use standard Maven goals for instance: > mvn install Builds and installs the project > mvn clean Cleans all artifacts etc.

How to get started with the Seal.java library

This page gives a brief description on how to get started with the developing, enhancing or using the Seal.java library. This is an example page, where we describe how to get started using a set of chosen tools. Naturally, you are free to use other tools.

Installing and configuring a JDK

First you must download and install a JDK (JDK 1.4.2 or later). For configuration, please refer to How to configure the JDK

Checking out the Seal.java from Subversion

Download and install a free version of SmartSVN client from http://www.smartcvs.com/smartsvn/download.html Start the SmartSVN client and add a profile pointing to the Seal.java Subversion node Activate the menu Repository | Manage profiles... and click add Click Add SVN URL, enter http://svn.softwareborsen.dk/trunk and click OK Enter SOSI in Use this Profile name and click OK Check out the Seal.java component and demos Activate the menu Project | Check out... Select the SOSI repository profile and click Next Click Next again and enter the path to the directory you would like to check out into Click Next twice and Finish Check that the files ended up in the specified directory

Installing Maven
Download Maven from http://maven.apache.org/download.html Follow the installation guidelines on the same page (bottom part) That's it!

The first build

Open a command prompt (cmd on Windows) Change to the SOSI/modules Execute bootstrap.cmd (Windows) or bootstrap.sh (Unix) ... and be patient.

Page 4 / 10

If you see a "Build Successful" in the last part of the output, your development environment is bootstrapped and ready to use.

How to configure the JDK

SEAL 1.4+
Export Policy
JDK 1.4 and 5.0 are shipped with policy files that support strong but not unbounded encryption strength. However, SUN and IBM do distribute policy files that allow unbounded encryption strength which is needed by the SOSI component: Download og extract US_export_policy.jar and local_policy.jar from Sun 1.4.2: http://java.sun.com/j2se/1.4.2/download.html ('Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files' - in the bottom part of the page) Sun 1.5: http://java.sun.com/javase/downloads/index_jdk5.jsp ('Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files' - in the bottom part of the page) Sun 1.6: http://java.sun.com/javase/downloads/index.jsp ('Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files' - in the bottom part of the page) IBM 1.4.2: http://www-128.ibm.com/developerworks/java/jdk/security/142/ IBM 1.5: http://www-128.ibm.com/developerworks/java/jdk/security/50/

Copy these two files to $JRE_HOME/lib/security and overwrite the existing files. JCE Providers are now handled via properties in Seal. Hence there is no need to edit java.security, etc.

SEAL 1.0 - 1.3

Export Policy
JDK 1.4 is shipped with policy files that support strong but not unbounded encryption strength. However, SUN does distribute policy files that allow unbounded encryption strength which is needed by Seal.java: Download og extract US_export_policy.jar and local_policy.jar from Sun 1.4.2: http://java.sun.com/j2se/1.4.2/download.html (in the bottom part of the page) Sun 1.5: http://java.sun.com/javase/downloads/index_jdk5.jsp IBM 1.4.2: http://www-128.ibm.com/developerworks/java/jdk/security/142/

Copy these two files to $JRE_HOME/lib/security and overwrite the existing files.

Configuring JCE with support for RSA

The OCES certificates use SHA-1 secure hashing with RSA encryption based on 1024 bit keys. This combination of security is not supported by Sun's JCE provider implementation. Therefore you need to configure your JDK with a provider that does, e.g Bouncycastle:

Page 5 / 10

Bouncycastle Provider
Legions of the Bouncy Castle offers an Open Source JCE Provider that is widely used in projects outside of USA. To install the provider you need to do the following: Get bcprov-jdk14-132.jar from http://www.bouncycastle.org/download/bcprov-jdk14-132.jar. Copy bcprov-jdk14-132.jar to $JRE_HOME/lib/ext (note: on windows JRE_HOME is %JAVA_HOME%/jre) Open $JRE_HOME/lib/security/java.security i a text editor Add security.provider.[number]=org.bouncycastle.jce.provider.BouncyCastleProvider to the list of providers. On a SUN JRE, the bouncycastle provider must be placed right after the sun.security.provider.Sun provider. Rename all subsequent providers accordingly (i.e. ''security.provider.2'' to ''security.provider.3'' etc.)

Installing an Eclipse project for the seal component

Open a command prompt (cmd on Windows) Change to the SOSI/modules/seal directory and execute mvn eclipse:eclipse Open Eclipse and select File | Import... Select Existing project into Workspace Browse to the Root Directory i.e. SOSI/modules/seal A seal project should now appear in the "projects:" box. Click Finish

Configuring Eclipse
Right click the seal project in the package explorer and select Properties Select Java Build Path and select the Libraries tab Click Add variable and click Configure variables Click New and enter M2_REPO as name and select the folder: /.M2/repository. In Windows this is something like: C:/Documents and Settings//.m2/repository

Installing the Subversion plugin for Eclipse

Install the plugin using the SubClipse guide: http://subclipse.tigris.org/install.html. Right click the project in the "package explorer" and select Team | Synchronize with repository. This will bring you to the synchronization view in the "Team synchronization" perspective ... learn it and love it

Installing the Clover plugin for Eclipse

Download the plugin from http://www.cenqua.com/download.jspa Follow the installation guide on http://www.cenqua.com/clover/doc/eclipse/index.html SDSD has acquired a free license for Open Source projects, which can be obtained by emailing driftsop@sdsd.dk.

Configuring code templates

Open the windows | preferences dialog

Page 6 / 10

Navigate to java | code style | code templates and activate the import button Import the file /config/eclipse/codetemplates.xml

How to configure your subversion client

In order to have keyword substitution work correctly for new Java files added to subversion, you need to follow these steps: Open your subversion configuration file in a text editor On windows the file is found here: %APPDATA%/Subversion/config On unix/mac/linux you will find it here: ~/.subversion/config Remove the comment (#) in front of: enable-auto-props = yes Add the following line in the [auto-props] section *.java = svn:keywords=LastChangedDate !LastChangedRevision ! LastChangedBy !HeadURL Id This means that all new Java files, that are added to Subversion will have the svn:keywords property set correctly. If these keywords (e.g. $!LastChangedBy:$) are used in JavaDoc, they will get substituted by subversion when committed.

Configure Apache JMeter for load testing

When compiling, packaging, and testing there is no need to have JMeter installed. However, if you're releasing new versions and need to perform Maven life cycles "install", "deploy", "site" etc. you must currently have JMeter installed and configured locally. To do this, follow these steps: Download Apache JMeter from http://jakarta.apache.org/jmeter/ and install into a local folder, $jmeter_home Open modules/seal/profiles.xml and edit <jmeter.root> to match $jmeter_home You're good to go.

The Maven build environment will run performance tests as part of the integration-test phase, i.e. whenever you execute a life cycle phase which includes this step. The results of performance testing can be seen under target/*.jsl and via target/site/jmeter/index.html, which can be reached from the seal auto generated site.

Releasing the SOSI library

Please note that this section is subject to change, as these procedures are currently (spring 2009) being updated.

Preparing the release

First ensure that nobody has uncommitted changes Check that all metrics and reports show "good numbers" on the generated Maven site (under CruiseControl)

Page 7 / 10

Edit modules/changes.txt to document all interesting changes, additions, compatability problems etc. Commit modules/changes.txt Ensure that pom.xml files version numbers is increased to the new version (modules, seal, testtools, demo/provider, demo/client, demo/axis2-module, demo/client-axis2, demo/provideraxis2) If the xml format of IDCard is changed check that the versionnumber is increased Check that everything compiles and runs under JDK-1.4.2, JDK-1.5.0, JDK-1.6.0, IBMSDK1.4.2 Commit any changes

Making the release

Remove your previous SVN checkout (entirely!) Make a clean checkout from SVN Run the command builddist.cmd from the root of the /modules directory

Testing the release

Unzip the release from releases/sosi--complete.zip Start a command prompt and change to /sosi/bin Run the runtests.cmd command and check that no tests fails under JDK-1.4.2, JDK-1.6.0, IBMSDK-1.4.2 Run the runtests.cmd command and check that no tests fails under JDK-1.5.0 with BouncyCastle removed from classpath Run the runtesttools.cmd command and check that no tests fails under JDK-1.4.2, JDK-1.6.0, IBMSDK-1.4.2 Run the runtesttools.cmd command and check that no tests fails under JDK-1.5.0 with BouncyCastle removed from classpath

Publishing the release

Please note: Release publishing must be coordinated with SDSDs operator at driftsop@sdsd.dk. Commit release folder and edit the softwareborsen.dk site with the new release. Make a tag of trunk. Commit. Update versions in pom.xml to next version number. Commit. Send e-mail to all that are using the library.

Q&A
Q: I get an ExceptionInInitializerError when I try to use the seal library
Exception in thread "main" java.lang.ExceptionInInitializerError at java.lang.Class.forName0(Native Method) at java.lang.Class.forName(Class.java:141) at dk.sosi.seal.MainTester.class$(MainTester.java:22) at dk.sosi.seal.MainTester.suite(MainTester.java:23)

Page 8 / 10

at dk.sosi.seal.MainTester.main(MainTester.java:35) Caused by: dk.sosi.seal.vault.CredentialVaultException: Unable to load PKCS12 file java.io.ByteArrayInputStream@73a34b at dk.sosi.seal.vault.GenericCredentialVault.loadKeyPairFromPKCS12(GenericCredentia lVault.java:279) at dk.sosi.seal.vault.GenericCredentialVault.setSystemCredentialPair(GenericCredent ialVault.java:164) at dk.sosi.seal.vault.CredentialVaultUtil.getCredentialVault(CredentialVaultUtil.ja va:227) at dk.sosi.seal.TestPerformance.<clinit>(TestPerformance.java:60) ... 5 more Caused by: java.security.NoSuchProviderException: no such provider: BC at java.security.Security.getEngineClassName(Security.java:601) at java.security.Security.getImpl(Security.java:1044) at java.security.KeyStore.getInstance(KeyStore.java:199) at dk.sosi.seal.vault.GenericCredentialVault.loadKeyPairFromPKCS12(GenericCredentia lVault.java:273) ... 8 more

A: You have not installed a PKCS provider with the JDK. You will also get this exception if you did not install the "unbounded strength" policy files. Follow the instructions on HowToConfigureJava. Q: I get another ExceptionInInitializerError when I try to use the seal library

java.lang.reflect.InvocationTargetException at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:39) at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.jav a:25) at java.lang.reflect.Method.invoke(Method.java:585) at org.apache.axis.providers.java.MsgProvider.processMessage(MsgProvider.java:155) at org.apache.axis.providers.java.JavaProvider.invoke(JavaProvider.java:323) ... Caused by: java.lang.ExceptionInInitializerError at javax.crypto.Mac.getInstance(DashoA12275) at org.bouncycastle.jce.provider.JDKPKCS12KeyStore.engineLoad(Unknown Source) at java.security.KeyStore.load(KeyStore.java:1150) ... ... 34 more Caused by: java.lang.SecurityException: Cannot set up certs for trusted CAs at javax.crypto.SunJCE_b.<clinit>(DashoA12275) ... 42 more Caused by: java.security.PrivilegedActionException: java.security.InvalidKeyException: Public key presented not for certificate signature at java.security.AccessController.doPrivileged(Native Method) ... 43 more Caused by: java.security.InvalidKeyException: Public key presented not for certificate signature at org.bouncycastle.jce.provider.X509CertificateObject.checkSignature(Unknown Source)

Page 9 / 10

at org.bouncycastle.jce.provider.X509CertificateObject.verify(Unknown Source) ... ... 44 more

A: We have seen this exception on Solaris, where the JRE from SUN comes with an additional security provider compared to the Windows JRE. The problem is fixed by moving down the provider according to the guidelines in HowToConfigureJava.

Q: The performance tests are extremely fast. Something must be wrong! A: Well the SOSI library is pretty fast. However in some cases old or bad seal*.jar files may have been copied to the /lib/junit directory. Remove all seal*.jar files and rerun the performancetests. Q: The build fails for me, but runs for everybody else that has checked out the project? A: Try issue a 'mvn -U install' from the modules directory. This will update all maven plugins needed by the build. Q: Running 'mvn -U install' downloads an extreme amount of software. Some of the downloads fails with 'Error transferring file ...' A: In some periods the central maven repositories are very busy and you may get broken connections. You should run the "bootstrap" script located in the modules directory. This will configure Maven to download dependencies from "sunsite", which is vastly superior (in speed) to the central Maven repositories. Q: I generated a pretty-printed XML string through the XmlUtil.node2String method, and now the signature verification fails when trying to deserialize the document A: Pretty-printing an XML document introduces white-space elements into the SignedInfo element in the XML document. These white-space elements are not removed by the C14N algorithm (intentionally!) which breaks the signature. Use the XmlUtil.removeFormatting() method before deserializing. Q: I serialized an IDCard using XmlUtil.node2String on the DOM generated by IDCard.serialize2DOMDocument, but deserializing fails because of missing namespace declarations in the serialized IDCard A: You probably have an older version of Xalan on your classpath that does not generate namespace declarations correctly. Make sure you are using the version of Xalan shipped as a depency with the SOSI Library. The issue has been seen on Tomcat (version 5.2.25) which has its own older version of Xalan. There the problem was solved by placing xalan-<version>.jar from the SOSI Library distribution into $TOMCAT_HOME/common/endorsed/.

Page 10 / 10