source: TI12-security/trunk/java/axis2/xmlbWsseEchoClient/src/wssecurity/test/security/ndg/README.txt @ 4112

Subversion URL: http://proj.badc.rl.ac.uk/svn/ndg/TI12-security/trunk/java/axis2/xmlbWsseEchoClient/src/wssecurity/test/security/ndg/README.txt@4112
Revision 4112, 7.0 KB checked in by cbyrom, 12 years ago (diff)

Create new package with Java client for SessionMgr? service and associated
tests + add required config files + add utility class, InstallCert? - to
allow the import of server certs required for the ssl comms + update
related docs.

Line 
1Instructions for getting a working Java client
2-------------------------------
3
41. Download and unpack axis2-1.4 (http://ws.apache.org/axis2/download/1_4/download.cgi#std-bin)
52. Download and unpack rampart1.3 (http://ws.apache.org/rampart/download/1.3/download.cgi)
63. Ensure that the AXIS2_HOME environment variable is set correctly then
7run 'ant' in the $RAMPART_HOME/samples dir - this will copy the required rampart
8files into the axis2 install
94. Download wss4j-1.5.3.jar (http://mirror.fubra.com/ftp.apache.org/ws/wss4j/) and add to the $AXIS2_HOME/lib dir
105. Create a java project in eclipse
116. In the top level directory of this project, run the following command:
12
13%AXIS2_HOME%\bin\WSDL2Java -uri <service>.wsdl -p ndg.security.client -d adb -s
14
15NB: '-uri' should point to the wsdl to create the service against (can use
16absolute file path if the wsdl if available locally)
17 '-p' specifies the package to create
18 '-d' specifies the databindings to create - here we use the Axis Data Binding default - which is a simple, but not too flexible approach
19 (other options are available: xmlbeans - http://ws.apache.org/axis2/1_4/userguide-creatingclients-xmlbeans.html; and
20 JiBX - http://ws.apache.org/axis2/1_4/userguide-creatingclients-jibx.html)
21 '-s' specifies synchronous invocation - i.e. the client will wait for a response - use '-a' for
22 asynch clients - i.e. with callback handlers)
23 
24 7. Refresh the project in eclipse to import the generated stub file - which will be called
25 <service>ServiceStub.java (NB, if other binding types are used there will likely be many more
26 stub files produced)
27 8. Open the <service>ServiceStub.java file and correct the package name, if need be.  Also make
28 use of eclipse's auto formatting function (ctrl-F) to tidy up the code.
29 9. Add the contents of $AXIS2_HOME/lib to the build classpath - this should then remove all
30 the errors displayed in eclipse for the stub file.
31 10. Create a new class - <service>Client.java - in the same package as the stub file.
32 11. The new class should be based on the example client jar in this folder - i.e. EchoClientADB.jar
33 12. Download geronimo-j2ee_1.4_spec-1.0.jar and add this to the classpath (otherwise you end up with
34 a org.apache.axis2.deployment.DeploymentException: javax/jms/JMSException error when running the client)
35 13. Copy the $AXIS2_HOME\repository\modules directory to the top level of the project - otherwise you'll get errors involving rampart not being engaged (NB, you can probably
36 avoid this step by setting up the build path to include the original axis2 install home?)
37 14. Copy the $AXIS2_HOME\conf directory to the top level of the project
38 15. Copy the client.properties file from this project into the top level project directory
39 16. Set up security keys to use:
40        a) $JAVA_HOME\bin\keytool -genkey -alias client -keystore client.jks -keypass apache -storepass apache -keyalg RSA
41        (NB, can adjust names, but key needs to be RSA format to be accepted by the python ZSI webservice library also,
42        best to use the default keystore type of 'JKS' - since 'PKCS12' doesn't allow trusted certificates to be stored - so
43        it is not possible to store the service key - i.e. step (c), below)
44       
45        b) The key now needs to be signed by a Certificate Authority (CA) (to allow ZSI processing to complete successfully):
46                i) Firstly generate a certificate request via:
47
48$JAVA_HOME\bin\keytool -certreq -keystore client.jks -storepass apache -alias client -file client.cert.req
49
50                ii) Now, to get hold of a Certificate Authority key pair, copy the index.txt. openssl.cnf and serial files from
51                axis2/xmlbWsseEchoclient/opensslFiles/ (originally from http://wso2.org/library/174)
52                iii) Run,
53               
54openssl req -x509 -newkey rsa:1024 -keyout cakey.pem -out cacert.pem -config openssl.cnf
55                (NB, some of the DN data that you input whilst running this command will need to match the DN
56                data of the generated key that you want to sign - so try and ensure the data is similar - especially, avoid
57                using the default values since these are not the 'Unknown' values that the keytool provides)
58
59                iv) Create new certificates signed by the CA key using:
60
61openssl ca -config openssl.cnf -out client.pem -infiles client.cert.req
62                (NB, this command will fail if the DN data between the CA cert and the generated key mismatches significantly - as described in (iii)
63
64                v) To import the new signed key into the keystore, need to put into binary format:
65               
66openssl x509 -outform DER -in client.pem -out client.cert
67               
68                and do the same for the CA certificate:
69               
70openssl x509 -outform DER -in cacert.pem -out cacert.cert
71
72                vi) Lastly, import both the CA certificate and the new key (NB, the CA cert needs to be imported first -
73                therwise you'll get a 'keytool error: java.lang.Exception: Failed to establish chain from reply')
74                               
75$JAVA_HOME\bin\keytool -import -file cacert.cert -keystore client.jks -storepass apache -alias ca
76$JAVA_HOME\bin\keytool -import -file client.cert -keystore client.jks -storepass apache -alias client
77
78        c) The last thing to do is import the public key of the service into the client keystore:
79
80%JAVA_HOME%\bin\keytool -import -alias service -file service.cert -keystore client -storepass apache
81
8217. Edit the contents of client.properties to ensure the file and password properties are set correctly.
8318. Edit the contents of $AXIS2_HOME\conf\axis2.xml adjusting the rampart set up as appropriate.  NB, the
84example file included in this codebase (axis2/xmlbWsseEchoclient/conf/axis2.xml) should be sufficient for
85the purposes here.  The README.txt file in axis2/xmlbWsseEchoclient/conf/ gives a more detailed explanation
86of the various configurations of this file.
8719. Include a password callback class, if this is set in axis2.xml, in the source code structure - NB, the
88basic PWCBHandler.java, included in this directory, can be used as a starting point.
8920. Adjust the server configuration file - to include the CA cert file in pem format - i.e.
90as created in step 16(iii) in the trusted CA cert file list.
9121. Start up the service associated with the wsdl used in step 6. and run the client as a
92java app - with luck the service should return without a problem.
93
94Further notes/examples
95-------------------
96XmlBwsseEchoClient.java is a client that uses xmlbeans bindings - to get this to work, you need to run the
97build in its top level directory - 'ant client.jar' - then include the produced XBeans-packaged.jar file
98in the build path.
99
100EchoClientProgrammatical.java is a client that sets up the wss settings programmatically.
101
102EchoClientADB.java is a client that uses the Axis Data Bindings.
103
104Running Tests
105-----------------
106The EchoClientADBTest class contains a number of tests to exercise the EchoClientADB class
107under a variety of circumstances.  To get this running, edit the test.properties file so that
108the configuration dir and the endpoint url are correct.  NB, the endpoints are currently set
109to allow tcpmon to be connected into the system - i.e. input port 7000, service port 7100.
Note: See TracBrowser for help on using the repository browser.