Seal.Java Maintainer’s 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
Configuring the build environment ...................................................................................................... 3
Subversion ........................................................................................................................................ 3
Directory Structure ........................................................................................................................... 3
Maven Goals .................................................................................................................................... 3
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
URL
OS
Tortoise SVN
http://tortoisesvn.tigris.org
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
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
Page 3 / 10
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.
If you see a "Build Successful" in the last part of the output, your development environment is
bootstrapped and ready to use.
Page 4 / 10
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
Navigate to java | code style | code templates and activate the import button
Import the file /config/eclipse/codetemplates.xml
Page 6 / 10
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)
Edit modules/changes.txt to document all interesting changes, additions, compatability
problems etc.
Commit modules/changes.txt
Page 7 / 10




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 SDSD’s 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)
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)
Page 8 / 10
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)
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.
Page 9 / 10
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