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

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

Add info on the different example clients in the README doc.

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
36 14. Copy the $AXIS2_HOME\conf directory to the top level of the project
37 15. Copy the client.properties file from this project into the top level project directory
38 16. Set up security keys to use:
39        a) $JAVA_HOME\bin\keytool -genkey -alias client -keystore client.jks -keypass apache -storepass apache -keyalg RSA
40        (NB, can adjust names, but key needs to be RSA format to be accepted by the python ZSI webservice library also,
41        best to use the default keystore type of 'JKS' - since 'PKCS12' doesn't allow trusted certificates to be stored - so
42        it is not possible to store the service key - i.e. step (c), below)
43       
44        b) The key now needs to be signed by a Certificate Authority (CA) (to allow ZSI processing to complete successfully):
45                i) Firstly generate a certificate request via:
46
47$JAVA_HOME\bin\keytool -certreq -keystore client.jks -storepass apache -alias client -file client.cert.req
48
49                ii) Now, to get hold of a Certificate Authority key pair, copy the index.txt. openssl.cnf and serial files from
50                axis2/xmlbWsseEchoclient/opensslFiles/ (originally from http://wso2.org/library/174)
51                iii) Run,
52               
53openssl req -x509 -newkey rsa:1024 -keyout cakey.pem -out cacert.pem -config openssl.cnf
54                (NB, some of the DN data that you input whilst running this command will need to match the DN
55                data of the generated key that you want to sign - so try and ensure the data is similar - especially, avoid
56                using the default values since these are not the 'Unknown' values that the keytool provides)
57
58                iv) Create new certificates signed by the CA key using:
59
60openssl ca -config openssl.cnf -out client.pem -infiles client.cert.req
61                (NB, this command will fail if the DN data between the CA cert and the generated key mismatches significantly - as described in (iii)
62
63                v) To import the new signed key into the keystore, need to put into binary format:
64               
65openssl x509 -outform DER -in client.pem -out client.cert
66               
67                and do the same for the CA certificate:
68               
69openssl x509 -outform DER -in cacert.pem -out cacert.cert
70
71                vi) Lastly, import both the CA certificate and the new key (NB, the CA cert needs to be imported first)
72                               
73$JAVA_HOME\bin\keytool -import -file cacert.cert -keystore client.jks -storepass apache -alias ca
74$JAVA_HOME\bin\keytool -import -file client.cert -keystore client.jks -storepass apache -alias client
75
76        c) The last thing to do is import the public key of the service into the client keystore:
77
78%JAVA_HOME%\bin\keytool -import -alias service -file service.cert -keystore client -storepass apache
79
8017. Edit the contents of client.properties to ensure the file and password properties are set correctly.
8118. Edit the contents of $AXIS2_HOME\conf\axis2.xml adjusting the rampart set up as appropriate.  NB, the
82example file included in this codebase (axis2/xmlbWsseEchoclient/conf/axis2.xml) should be sufficient for
83the purposes here.  The README.txt file in axis2/xmlbWsseEchoclient/conf/ gives a more detailed explanation
84of the various configurations of this file.
8519. Include a password callback class, if this is set in axis2.xml, in the source code structure - NB, the
86basic PWCBHandler.java, included in this directory, can be used as a starting point.
8720. Start up the service associated with the wsdl used in step 6. and run the client as a
88java app - with luck the service should return without a problem.
89
90Further notes/examples
91-------------------
92XmlBwsseEchoClient.java is a client that uses xmlbeans bindings - to get this to work, you need to run the
93build in its top level directory - 'ant client.jar' - then include the produced XBeans-packaged.jar file
94in the build path.
95
96EchoClientProgrammatical.java is a client that sets up the wss settings programmatically.
97
98EchoClientADB.java is a client that uses the Axis Data Bindings.
Note: See TracBrowser for help on using the repository browser.