Secure SOAP Web Service over SSL on Jboss AS 7 Server

SSL provides three security services: mutual authentication, confidentiality and integrity. Mutual or peer authentication is the process where the server and the client authenticate each other through verifying the provided digital certificate so that both parties are assured of the others' identity. But very often the server doesn't challenge client for authentication. The article describes both cases of authentication.

1. Server Authentication

Let's start with the case where server doesn't challenge client.

1.1 Create a Simple RPC Web Service

To add transport-layer security to the web service, please start with implementing simple RPC servlet-based web service with JAX-WS.

1.2 Configure Jboss AS 7 Server

Generate a Keystore

First we need generate a secret key/certificate and store it in a "key store" file. It can be done with keytool utility. The password for encryption is "clouds".


keytool -genkey -alias examclouds -keyalg RSA -keystore examclouds.keystore -validity 10950
Enter keystore password: clouds
Re-enter new password: clouds
What is your first and last name?
  [Unknown]:  examclouds.com
What is the name of your organizational unit?
  [Unknown]:  Examclouds
What is the name of your organization?
   [Unknown]:  examclouds
What is the name of your City or Locality?
   [Unknown]:  Kharkiv
What is the name of your State or Province?
   [Unknown]:  Kharkiv
What is the two-letter country code for this unit?
   [Unknown]:  UA
Is CN=examclouds.com, OU=Examclouds, O=examclouds, L=Kharkiv, ST=Kharkiv, C=UA correct?
   [no]:  yes

Enter key password for <examclouds> clouds
    (RETURN if same as keystore password):
Re-enter new password: clouds

Configure SSL Support on Jboss

To do it add a "SSL HTTP/1.1 Connector" entry in standalone/configuration/ standalone.xml file:


<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
        <ssl name="examclouds-ssl" key-alias="examclouds" password="clouds"
        certificate-key-file="../standalone/configuration/examclouds.keystore" protocol="TLSv1"/>
    </connector>
    <virtual-server name="default-host" enable-welcome-root="true">
               ...
    </virtual-server>
</subsystem>

More details about server configuration can be found on Jboss Documentation.

1.3 Import a Server Certificate to the Client Truststore

Export the Server Certificate


keytool -export -alias examclouds -keystore examclouds.keystore -storepass clouds
-file server.cer
Certificate stored in file <server.cer>
                 

Deliver the Server Certificate to the Client

Copy generated on the previous step file <server.cer> to the client location.

Create the Client Truststore and Import the Server Certificate to the Client Truststore


keytool -import -v -trustcacerts -alias examclouds -keystore client_ts.jks -storepass mypass
-keypass clouds -file server.cer
Owner: CN=examclouds.com, OU=Examclouds, O=examclouds, L=Kharkiv, ST=Kharkiv, C=UA
Issuer: CN=examclouds.com, OU=Examclouds, O=examclouds, L=Kharkiv, ST=Kharkiv, C=UA
Serial number: 44aca6f6
Valid from: Thu Mar 10 23:17:38 EET 2016 until: Sat Mar 03 23:17:38 EET 2046
Certificate fingerprints:
         MD5:  57:80:14:F8:5B:99:A4:47:96:B7:E2:64:91:40:F5:D6
         SHA1: EC:FB:9D:90:F6:5F:76:11:D9:BC:60:B2:2C:E6:BA:A5:17:5E:58:7A
         SHA256: 54:1C:4A:0A:14:9B:0E:DE:E0:49:9F:BF:A2:EC:1B:FA:A3:AB:59:41:30:31:60:B4:6E:72:E9:4C:9E:5A:C1:D6
         Signature algorithm name: SHA256withRSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 01 3E F0 55 0B 4C 04 42   A5 49 3D C8 8F 37 84 90  .>.U.L.B.I=..7..
0010: 90 CB 6E BE                                        ..n.
]
]

Trust this certificate? [no]:  yes
Certificate was added to keystore
[Storing client_ts.jks]
                   

1.4 Modify web.xml

SSL requires CONFIDENTIAL transport-guarantee to be configured.

                               
<security-constraint>
      <web-resource-collection>
            <web-resource-name>ECCollection</web-resource-name>
            <url-pattern>/ExamClouds</url-pattern>
            <http-method>POST</http-method>
      </web-resource-collection>
      <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
</security-constraint>

1.5 Deploy an Application and Create a Web Service Client

Deploy an application, test it and create a web service client how it is described in RPC servlet-based web service with JAX-WS.

1.6 Run a Web Service Client

Finally we are ready to invoke our web service.

Configure HOSTS File

If you run web service and client locally, make sure that your C:\Windows\System32\ drivers\etc\hosts file contains entry:

                               
127.0.0.1 localhost

Modify the Client

Our client requires several changes:

  1. Modify the URL of the web service to use HTTPS instead of HTTP; and port 8443, which is the default one for JBoss Web to listen for secure connections.
  2. Add following JVM parameters to use the client truststore:
    
       -Djavax.net.ssl.trustStore=client_ts.jks
       -Djavax.net.ssl.trustStorePassword=mypass
       -Djavax.net.debug=all
  3. Code in a static initialization block is used for localhost test only. Its purpose is to solve the issue which happens when CN (Common Name) in the certificate mismatches with host name in the URL.
                      
package example.client;

import java.net.MalformedURLException;
import java.net.URL;

public class ExamCloudsClient {
    public static String CLIENT_WSDL = "https://localhost:8443/ws1-1.0-SNAPSHOT/ExamClouds?wsdl";

    static {
        //for localhost testing only
        javax.net.ssl.HttpsURLConnection.setDefaultHostnameVerifier(
                new javax.net.ssl.HostnameVerifier() {

                    public boolean verify(String hostname,
                                          javax.net.ssl.SSLSession sslSession) {
                        return hostname.equals("localhost");
                    }
                });
    }

    public static void main(String[] args) throws MalformedURLException {
        ExamCloudsImplService service = new ExamCloudsImplService(new URL(CLIENT_WSDL));
        ExamClouds port = service.getExamCloudsImplPort();

        System.out.println(port.getSiteName());
        System.out.println(port.getSiteDescription());
    }
}
                      

2. Server and Client Authentication

To add client authentication we need to change a previous example a little bit.

2.1 Create a Simple RPC Web Service

The same actions as in 1.1.

2.2 Configure Jboss AS 7 Server

Generate the server keystore and configure SSL support on jboss server as described in 1.2. Add verify-client element to standalone.xml file, which makes the server to challenge the client. And specify truststore for the server. A keystore and a truststore can be the same file, as we did it:


<subsystem xmlns="urn:jboss:domain:web:1.1" default-virtual-server="default-host" native="false">
    <connector name="http" protocol="HTTP/1.1" scheme="http" socket-binding="http"/>
    <connector name="https" protocol="HTTP/1.1" scheme="https" socket-binding="https" secure="true">
        <ssl name="examclouds-ssl" key-alias="examclouds" password="clouds"
         certificate-key-file="../standalone/configuration/examclouds.keystore" protocol="TLSv1"
         verify-client="true" ca-certificate-file="../standalone/configuration/examclouds.keystore"/>
    </connector>
    <virtual-server name="default-host" enable-welcome-root="true">
               ...
    </virtual-server>
</subsystem>

2.3 Create a Client Keystore and Key


keytool -genkey -alias client -keypass mypass -storepass mypass -keystore client_ks.jks
What is your first and last name?
 [Unknown]: Exam Client
What is the name of your organizational unit?
 [Unknown]: Exam Client Org Unit
What is the name of your organization?
 [Unknown]: Exam Client Org
What is the name of your City or Locality?
 [Unknown]: Kharkiv
What is the name of your State or Province?
 [Unknown]: Kharkiv
What is the two-letter country code for this unit?
 [Unknown]: UA
Is CN=Exam Client, OU=Exam Client Org Unit, O=Exam Client Org, L=Kharkiv, ST=Kharkiv, C=UA correct?
 [no]: yes

2.4 Import a Client Certificate to the Server Truststore

Export the Client Certificate


keytool -export -alias client -keystore client_ks.jks -storepass mypass -file client.cer
Certificate stored in file <client.cer>

Deliver Client Certificate to the Server

The <client.cer> file should be stored on the server, in "../standalone/configuration" directory for Jboss AS 7.

Add the Client Certificate to the Server Truststore.

Import client certificate with keytool utility to the server truststore:


keytool -import -v -trustcacerts -alias client -keystore examclouds.keystore -keypass clouds
-file client.cer
Enter keystore password: clouds
Owner: CN=Exam Client, OU=Exam Client Org Unit, O=Exam Client Org, L=Kharkiv, ST=Kharkiv, C=UA
Issuer: CN=Exam Client, OU=Exam Client Org Unit, O=Exam Client Org, L=Kharkiv, ST=Kharkiv, C=UA
Serial number: 20062a5b
Valid from: Thu Mar 10 23:51:31 EET 2016 until: Thu Jun 09 00:51:31 EEST 2016
Certificate fingerprints:
         MD5:  99:7C:2B:14:D0:74:E0:C8:41:E6:6E:27:BC:7C:E0:9C
         SHA1: 30:55:A0:41:55:85:F8:99:8D:FD:64:71:C2:F7:C0:83:44:EA:E1:7E
         SHA256: 12:B5:43:8A:16:0E:38:DF:35:3E:25:DD:3B:2D:53:1B:52:BF:2B:D1:72:2E:D7:69:C7:DF:27:09:CE:DC:F2:E2
         Signature algorithm name: SHA1withDSA
         Version: 3

Extensions:

#1: ObjectId: 2.5.29.14 Criticality=false
SubjectKeyIdentifier [
KeyIdentifier [
0000: 06 CF 99 31 E3 76 B6 63   E2 1C 00 BD A8 5E 92 6B  ...1.v.c.....^.k
0010: AD E6 61 50                                        ..aP
]
]

Trust this certificate? [no]:  yes
Certificate was added to keystore
[Storing examclouds.keystore]

2.5 Import a Server Certificate to the Client Truststore

The same as described in 1.3 above.

2.6 Modify web.xml

Authentication method should be set to CLIENT-CERT.

                               
<security-constraint>
      <web-resource-collection>
            <web-resource-name>ECCollection</web-resource-name>
            <url-pattern>/ExamClouds</url-pattern>
            <http-method>POST</http-method>
      </web-resource-collection>
      <user-data-constraint>
            <transport-guarantee>CONFIDENTIAL</transport-guarantee>
      </user-data-constraint>
</security-constraint>

<login-config>
      <auth-method>CLIENT-CERT</auth-method>
</login-config>

2.7 Deploy an Application and Create a Web Service Client

The same as in 1.5.

2.8 Run a Web Service Client

The same as in 1.6. The only change that should be done is adding client keystore to the JVM parameters:


-Djavax.net.ssl.trustStore=client_ts.jks
-Djavax.net.ssl.trustStorePassword=mypass
-Djavax.net.ssl.keyStore=client_ks.jks
-Djavax.net.ssl.keyStorePassword=mypass
-Djavax.net.debug=all


0 comments
Leave your comment: