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/.
Enter the password to open this PDF file:
File name:
-
File size:
-
Title:
-
Author:
-
Subject:
-
Keywords:
-
Creation Date:
-
Modification Date:
-
Creator:
-
PDF Producer:
-
PDF Version:
-
Page Count:
-
Preparing document for printing…
0%
Σχόλια 0
Συνδεθείτε για να κοινοποιήσετε σχόλιο