How to get started with the Seal.java library - Digitaliser.dk

Page
1

/
10

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
2

/
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 b
uild

................................
................................
................................
................................
...

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 Eclip
se

................................
................................
...........................

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
3

/
10

Changelog

Date

Change

Author

2007
-
2008

TWiki revision

JRI, CC

March 10, 2009

Microsoft Word Revision, minor updates

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
Command Line

http://metissian.com/projects/macosx/subversion

Mac OS X

You can also use a Subversion client embedded in your favori
te 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/, jme
ter
-
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


* jmet
er
-
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 applicat
ions


* 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 An
t 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
4

/
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
Sea
l.java

library. This is an example page, where we descri
b
e 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 conf
iguration, 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 cli
ck
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 lik
e to check out into



Click
Next

twice and
Finish



Check that the files ended up in the specified directory

Installi
ng 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 p
art of the output, your development environment is
bootstrapped and ready to use.



Page
5

/
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 IB
M 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://j
ava.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.j
sp

('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/sec
urity/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 dis
tribute policy files th
at 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

(i
n 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 us
e

SHA
-
1 secure hashing with RSA encryption based on 1024 bit k
eys.
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
6

/
10

Bouncycastle Provider

Legions of the Bouncy Castle

offer
s

an Open Source JCE Pro
vider 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
-
j
dk14
-
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 p
roject 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

a
nd 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 v
iew 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 o
n
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 templat
es



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
7

/
10

How to configure your subversion client

In order to have keyword substitution work cor
rectly 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/c
onfig



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, an
d 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/cha
nges.txt


Page
8

/
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/provider
-
axis2)



If the xml format of IDCard is changed check that the versi
onnumber is increased



Check that everything compiles and runs under JDK
-
1.4.2, JDK
-
1.5.0, JDK
-
1.6.0, IBMSDK
-
1.4.2



Commit any changes

Making the release



Remove your previous SVN checkout (entirely!)



Make a clean checkout from SVN



Run the command builddist.c
md 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

comman
d 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 r
elease 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:2
2)


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
9

/
10


at
dk.sosi.seal.vault.GenericCredentialVault.setSystemCredentialPair(GenericCredent
ialVault.java:164)


at
dk.sosi.seal.vault.CredentialVaultUtil.g
etCredentialVault(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.getEngineC
lassName(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.jav
a: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.r
eflect.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.jc
e.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
10

/
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 brok
en
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
-
print
ed 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.ser
ialize2DOMDocument, 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 in
to $TOMCAT_HOME/common/endorsed/.