JAX-WS Secure Web Services with Signatures and Encryption: WS-Security with Metro and WSIT

0 Flares Twitter 0 Facebook 0 Google+ 0 LinkedIn 0 Email -- Filament.io 0 Flares ×

Java Web Services: Create Secure JAX-WS Metro Web Service Signed and Encrypted Using Public-Key Cryptography Asymmetric Encryption

Security is the primary concern when web services exchange critical business data. WS-Security is an is an extension to SOAP to apply security to web services. It is one of the main part of WS-* specification from OASIS. WS-Security focuses on XML Signature and XML Encryption to provide end-to-end security.
In this tutorial, we discuss about developing secure web services with signature and encryption using public-key cryptography method. Using asymmetric encryption and message signing, we secure web service and achieve message confidentiality, integrity and authenticity, the three main aspects of WS-Security. We use JAX-WS reference implementation Metro web service stack to develop and run the secure web service java example and secure web service client.

Creating Secure JAX-WS Metro Web Service Using WSIT to Use Public-key Cryptography.

In this article, we will use the same sample program which we discussed in JAX-WS and Secure Java Web Services using UsernameToken : WS-Security with Metro and WSIT.
It is a good idea to read the above article first and understand how the basic plain text UsernameToken Policy is implemented. That will help you to understand WSIT configuration required for this example. The only difference here is that, we are not going to use usernameToken here but we use public-key asymmetric encryption and signature to achieve the three major aspects of WS-security namely confidentiality, authenticity and integrity.

Create keystore and self signed certificates for web service message signature and encryption

To make the web service secure using signature and encryption, we need to have keystore, public-private keypairs and certificates configured for client and server. We can utilize the java keytool tool to create and maintain keystores. The keystore is a file that contains key and certificate entries in encrypted form. You need keystore password to access keystore and keypassword to maintain private key.
For testing purpose, you can create self signed certificates. Depends on need, you can purchase digital certificates from certificate authorities such as VeriSign, Thawte and Geotrus.
You need to create keystore and keys for client and server. Then export and import (self signed/trusted) certificates from and to client and server. If you need encryption on both ends (request and response), you need to import client certificate to server keystore and server certificate to client keystore. This is because, encryption requires access to public key of the other party. This is available in certificate. If you don’t need to encrypt the response from server to client, you don’t need to export the client certificate to server if the certificate is signed by a trust authority. If it is self signed, you need import client certificate to server since the server cannot validate self signed certificate otherwise.

Keep the keystores and certificates ready so that we can use the same in our secure JAX-WS web service example.

Quick look at Public-key cryptography

Public-key cryptography offers authenticity, confidentiality and integrity. These three are the major aspects of message exchange security. Integrity ensure that the message is received without modification, authenticity means that the origin of the message can be verified and confidentiality ensure that only the intended recipient of a message has access to the message content.

Ensuring confidentiality using public-key cryptography

Public-key cryptography uses asymmetric key algorithm, where, each user has a pair of cryptographic keys. The public key which is used to encrypt the message is distributed either publicly or to the client, who sends the message. Only the private key, which is confidential and is available only with the user, can be used to decrypt the encrypted message. The message cannot be decrypted by anyone who does not possess the matching private key. Since only the owner has the private key and only he can decrypt the message. This ensures confidentiality.

Digital certificates (ex. X.509 v3 digital certificate – X.509 is an ITU-T standard for a public key infrastructure (PKI)) is an electronic document that uses a digital signature to bind a public key with an identity. This certificate, which is essentially a wrapper around public key, is used to verify that the public key belongs to an entity. This wrapper is typically signed by a trusted signing authority.

Ensuring Authenticity and Integrity Using Public-key Cryptography

The sender calculate the hash value/digest of the message using hash algorithm and then encrypt that digest using your private key and send the encrypted digest value with the message. The receiver can use the same hash algorithm on that message, then decrypt the supplied encrypted digest using sender’s public key. Now the receiver can compare the two values and if they match, the receiver can then be certain that the message is from you. This ensures authenticity.

This also ensures message integrity because it is really hard to make any changes to a message without changing the hash value for that message, or to find another message with the same hash value as a original message.

JAX-WS Web Service SEI,Implementation Classes and WSIT configurations

You will be using the same SEI and implementation classes used for UsernameToken example. Here you don’t have to include the MyServicePasswordValidator class as that is meant for UsernameToken example.
There is no change in web.xml. In sun-jaxws.xml you can disable the MTOM by changing the line enable-mtom=”false” since we don’t want to try MTOM feature here.
The only difference is the configuration of WS Policy in WSDL files. That is explained below.

Update the Server WSIT file to include the signatures and encryption to make the web service WS-Security complaint.


The above “wsit-com.globinch.service.MyWebService.xml” file now includes the security policy configurations. This is explained below.


Indicates that the this policy element is configured to use Public-key asymmetric cryptography during message exchange.


Indicates that the public key (to sign the message) will be in the form of an X.509 certificate and will be sent with each message from the client to server.(Here from server to client also uses the same policy)


Indicate the algorithm used for signing.


Indicate that timestamp will be used with each message. A sample in a message is given below.



Indicates that signing will be done on the entire header or body of the message.


Indicate the message parts to be signed.


Indicate the message parts to be encrypted.


This tells runtime to use the certificate. Alternate is to use

that tells the runtime to use thumbprint reference instead for the certificate. If your certificate supports SKI (Subject Key Identifier) then you can use the default <sp:WssX509V3Token10>.

You also add the server keystore details by adding <wsss:KeyStore> policy element. Here you need to provide the location of the keystore also. You can either provide the absolute location or just the keystore name. If no absolute location is provided the metro/wsit runtime will look for the keystore META-INF child directory of a directory in the classpath.

Now our service is ready for deployment. Once you deploy the service you can access the WSDL file from the URL similar to the below.
You will see the WSDL as follows


Creating Secure Web Service Client Using Signature and Encryption

To update the web service proxy classes you need to run the wsimport utility as explained in the UsernameToken example

wsimport -keep -XadditionalHeaders http://localhost:8080/MyService/?wsdl

Now you need to add the WS security policy configuration to client WSIT file. Update the client WSIT file (MyWebServiceService.xml) to include the signatures and encryption to make the web service WS-Security complaint.





As with server you need to configure the in wsit file as above. You can either provide the absolute location or just the keystore name. If no absolute location is provided the metro/wsit runtime will look for the keystore META-INF child directory of a directory in the classpath.
You don’t need to change wsit-client.xml or web.xml.

Now you can deploy the application and run the client. You can see the messages transferred between clinet and server are signed and encrypted. For example when the client invokes the “greetCustomer(name)” method of the MyWebService, you will see the request and response similar to the below.

Sample signed and encrypted Web Service Request

---[HTTP request - http://localhost:8080/MyService/]---
Accept: text/xml,
Content-Type: text/xml; charset=utf-8
User-Agent: Metro/2.2.1-1 (tags/2.2.1-1-7267; 2012-08-30T14:04:51+0000)
JAXWS-RI/2.2.7 JAXWS/2.2 svn-revision#unknown

										CN=localhost, OU=home, O=home, L=city,
											ST=state, C=in

Sample signed and encrypted Web Service Response

---[HTTP response - http://localhost:8080/MyService/
- 200]---
null: HTTP/1.1 200 OK
Content-Type: text/xml;charset=utf-8
Thu, 16 May 2013 13:00:09 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked

										CN=localhost, OU=home, O=home, L=city,
											ST=state, C=in


  • The private key password and keystore passwords are made available to the metro runtime to encrypt and sign messages. This may be exposed if someone gets access to the source code. It is recommended to make additional security to secure private-key and keystore.
  • If you are using Tomcat web container to deploy this application please ensure that you must use same password for key password as well as keystore. Otherwsie you may get the following error.
    java.io.IOException: Cannot recover key  
            at org.apache.tomcat.util.net.jsse.JSSESocketFactory.init(JSSESocketFactory.java:465)  
            at org.apache.tomcat.util.net.jsse.JSSESocketFactory.createSocket(JSSESocketFactory.java:130)  
            at org.apache.tomcat.util.net.JIoEndpoint.init(JIoEndpoint.java:538)  Or 
    SEVERE: WSS1538: Exception during getting the private key
    java.security.UnrecoverableKeyException: Password must not be null
            at sun.security.provider.JavaKeyStore.engineGetKey(JavaKeyStore.java:124)
            at sun.security.provider.JavaKeyStore$JKS.engineGetKey(JavaKeyStore.java:55)
            at java.security.KeyStore.getKey(KeyStore.java:792)


0 Flares Twitter 0 Facebook 0 Google+ 0 LinkedIn 0 Email -- Filament.io 0 Flares ×

Related Posts

This Post Has 3 Comments

  1. Hi Binu,

    thank you for sharing the tutorials for JAX-WS-based web services utilizing WS-Security! I have been struggling quite some time to get web service and -client run in freshly created maven projects (Dynamic Web Project for the service itself and a separate JAR project for the client), but now everything runs quite smoothly 🙂

    Now I would like to give the XML signature/encryption variant a try. However your example uses a Security Policy TripleDesRsa15, which ends up in using #tripledes-cbc encryption from the XML Encryption 1.0 standard.

    Since the CBC mode has to be considered as broken, I am searching for an elegant solution to using AES encryption in GCM mode, as proposed in XML Encryption 1.1. Are you aware, if and how this can be accomplished with JAX-WS/Metro? Since WS-SecurityPolicy 1.3 does not include such a mode of operation, there won’t be any “standard” way of doing this?!

    Thanks in advance


  2. Hey Andreas,
    Thanks for the comments. I will be soon writing an article on AES encryption in GCM mode. I will update you once the article is published.

    Binu George

  3. Hi. I find this examples really really usefull.

    But I was wondering How do you managed to learn all of these things !!!!.

    I’ve tried with books but I can’t find the level of knowledge that you are showing on this post.

    Could you please guide me in order to learn about these topics?

Leave a Reply

Your email address will not be published. Required fields are marked *

Paged comment generated by AJAX Comment Page
© 2024 Globinch Java Forum - Theme by WPEnjoy · Powered by WordPress