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.

• Read keytool – Key and Certificate Management Tool to learn how to create and Keystore and Self Signed certificate and maintain them.

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.

		2013-05-16T08:41:35Z
		2013-05-16T08:46:35Z

 :

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.
http://{host}:{port}/MyService/?wsdl
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,
multipart/related
Content-Type: text/xml; charset=utf-8
SOAPAction:"http://service.globinch.com/MyWebService/greetCustomerRequest"
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


	
		
			
				2013-05-16T13:00:09Z
				2013-05-16T13:05:09Z
			
				
					MIIDWzCCAkOgAwIBAgIEacWOSTANBgkqhkiG9w0BAQUFADBeMQswCQYDVQQGEwJpbjEOMAwGA1UECBMFc3RhdGUxDTALBgNVBAcTBGNpdHkxDTALBgNVBAoTBGhvbWUxDTALBgNVBAsTBGhvbWU
					xEjAQBgNVBAMTCWxvY2FsaG9zdDAeFw0xMzA1MTUxNzA1MzNaFw0xMzA4MTMxNzA1MzNaMF4xCzAJBgNVBAYTAmluMQ4wDAYDVQQIEwVzdGF0ZTENMAsGA1UEBxMEY2l0eTENMAsGA1UEChMEaG9tZTENMAsGA1UECxMEaG9tZTESMBAGA1UEAxMJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAj5W7GLe5guoS1Q23xVnKU5FSOr8U4X
					Anj1ZoCyhyE0idzEzqG5k94dDz24tkcpvZzoMsIQ+cvEwjQJcvDSJboZHL78UlT5Zvu8K8Cnq9GEoC+5Uow+iaBIP2B4WP1U62sa+tpnL2f6mL+egkS+YVROMclspaJHIeSs2bmVvwbLC5paiD496yHXXa6c27wLmIX7nQMEp6uPDfCBXj9elDd/bNBjgm1mQkwu8DdFvnANTT/E6LAukmYCZwz/QUOLp+Vl0mPA62i8doQnGKHIZmCisIuALXwXEtLOpTjQsAgjOVQ
					NnIJIJJ7e6CbTpp54UoRdoY4CzhDK6P7P8+CjmOzwIDAQABoyEwHzAdBgNVHQ4EFgQUbK+AM4o4miKvscmneQKFQxE8zE4wDQYJKoZIhvcNAQEFBQADggEBABwLuZN4glEo1TlkwVcvT5pHz5RewdZSxpuwW2Rfvq0CGG3N3lvmGefgM5Ha5YYxFjDy/TDXipcupCyANXc7UgiZsFmfUhvpWL9y74lkvnVU62T5pht6+DpL2jVjlLx5zTFtI6Fh+yBdRN9XhpM5bLY+
					KAt9rrS0CnTnQOdowVjWuCG893Gr/0lna9GJ4b+vAMR3iKE7NYqly8a1ULcP9mXm3WmD4ut4gdhO2Rh038gMgaE/IWb+WILjd1lOG7E4x+FQKgas0eXeE8QxjU+Y6Z4dqiojW3ENJ8bj44oWEQo6kjcHbifMqsKSeeHGNQ0pTlyQ4VdlJ+XqZSIbTdY6FIs=
				
					
						
						
							
								
									
										CN=localhost, OU=home, O=home, L=city,
											ST=state, C=in
										173056135
									
								
							
						
						
							DmCPyY75NZOflXsZjL65sKMeylS2c03YtfjoS3g6FC9D/r5UqrejHYruPnXSNMADASUa47/All6PcfRNd50rUL0Yt6fofygvL5Cg6x5zrbqzgP/lqpLgw4pmy/gR04PkIJo8LX4pTkJrQ4rCW3CTs4KlSCzyD4hN6BNwBHbPBGTfGm+ghmlELO8Hwn6NEcfqdjCErBUWHdiuHaPzyee4Ld6lvvwZ
								EH1mVkqUEUgwH45G0yzi5xV+533TqdS8dFeuLsH0ZUHshtT5UNA/P0XjkmxkTlNn50GP4oVKbcAWonF0tx3QZKWYiIDL31gKtdkYFrMQTwIvzQCekA+djK3lMw==
							
						
						
							
						
					
					
						
							
								
							
							
							
								
									
										
									
								
								
								WXv4E01QJyY+7QRL6OSyjd7nqsk=
							
							
								
									
										
									
								
								
								wNApA3La+5PNpw5+SuTz9tZJ+eY=
							
						
						GJ4Ef
							cvGn/AWKDcND4P6xnbP34ROLDdQZqpcbRY4t5AgKuLrc65N3dUNaT/tRN+pHQslS/4Ik3SIZentrgCON1SErryMhZltoIUBgHnaKtunYHu8URzrq3kfXndLe3UFqHqAeVGvWQNCkWkG818h2Lzqy7JjjvIxek3Evre+DHTauaorHwhNBd4hqFMrN7UON3tJDNJyrjbeKqOroOSwgn8VEw9ky/Qn3UtXFVzTdhdVPkTvqdFmNW5/6pp4TU8jZ7djmOf9r48RciCcmjp7
							eNRHnUzMwjK5zYjObpyxjshyl7OBmfkyA7xRK45wZhx6hPD9uyjQCqZoWwqIb0+q1Q==
						
						
							
								
							
						
					
		
	
	
		
			
			
				mL4nMJ5OJFDpsY0JZ1wYXVZc+hjSX3djsiul+EqZ7t1k9IAyo0gf/UT380w0mEditEnTu4YkmMImy23pFwO/NHf
					wKiJjzhU3nr4Os63pcbKbNLBYb42O8zDqJtHiM/BHSz5Dzh2FFYWXlPolJ96DoA==
				
			
		
	

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
Date:
Thu, 16 May 2013 13:00:09 GMT
Server: Apache-Coyote/1.1
Transfer-Encoding: chunked


	
		
			
				2013-05-16T13:00:10Z
				2013-05-16T13:05:10Z
			
				
					MIIDWzCCAkOgAwIBAgIEClCghzANBgkqhkiG9w0BAQUFADBeMQswCQYDVQQGEwJpbjEOMAwGA1UECBMFc3RhdGUxDTALBgNVBAcTBGNpdHkxDTALBgNVBAoTBGhvbWUxDTALBgNVBAsTBGhvbWU
					xEjAQBgNVBAMTCWxvY2FsaG9zdDAeFw0xMzA1MTUxNzA1MTJaFw0xMzA4MTMxNzA1MTJaMF4xCzAJBgNVBAYTAmluMQ4wDAYDVQQIEwVzdGF0ZTENMAsGA1UEBxMEY2l0eTENMAsGA1UEChMEaG9tZTENMAsGA1UECxMEaG9tZTESMBAGA1UEAxMJbG9jYWxob3N0MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAlqGZPNokoOd38IfVnbgJuFSJvBgrUu
					45gPo4M6XvWuopWrjCDJRRRnae1aRF8p6/n/oUPvByGxL5QwA45ZAakusRpPiIgxgbq5sONCMqmlocU7OTIU6UVih33ssb2SD6kjbr4zUeLfjOTAc0p5HQJVFPYnPer7zntz9wRaaSrNY98koPmDLPKEe4Ub5hzFlunn6dyzhgdCvmBYvX0g8iccfXi28dHolDuRcUjfu2Pk1T06or3B3owPbWB/BKACNj7kIBACsx6dZGYG0Y7StWGXHbq0Fzaf+gRMZRErMcEsh3H
					DtewE4HAskXD28W6DiiLeH9rSly0hEoVY2C8mqL0wIDAQABoyEwHzAdBgNVHQ4EFgQUBkFKLe/fqjCmux53N8m6QSktdLkwDQYJKoZIhvcNAQEFBQADggEBAHe0cqrjCwj3k6kEdXkUyybMbEjnsASxeIkTPpRdySaMtvUaTOdnwC2eaZgfRyh7mffDubJjTJfmRN3uj31Tua0r1t3DuI+ZqNGI3x5KTVa5Zqx7VTrWkzGQ2itqhxfML6EW7zbEdo3qSVIsHZcVg4q5
					XacWRUy/SM56BdRAsRxlAKu/dUkIF486HMwBsILtsPNbVYmZUoNG25HeNRYEoV+APlSpjrlGHiKpgSgcrunc+lYq9YsC7ogCzzLRH0qq0CWuakiJs+rXp30SZEF/85cSgYa67bffc20DCU+Bj8TyUXfe15rWnrtj2IT5e30/PB6WPntHB3phP5riOhX2Org=
				
					
						
						
							
								
									
										CN=localhost, OU=home, O=home, L=city,
											ST=state, C=in
										1774554697
									
								
							
						
						
							RF0ASmWAupelcF9t8epLZ11z3A+qCQw7QKGPcPj6dBfqFTjVyL4gLoIGVMLYnfNVm89g+JqBNGgx22gRpPPyVeotHBkTQcAe/Tkedcvqvs/ZXdwjcr+NThmIBQMfN4ouyXKpdWPcflX2RntNbqVM03ci6YiDdywbCVbj+eTlj16Fv6RCdFbE0MHqVWtLwwRcFUZeqL7amD/kZI7qXxHq55MJNJa
								yWpzSBH4qzSV6aTrkcqh7NU97xupmgLHS2rIuJU75izuh2HsIzj3mvW2vx78zHryp72AhrQ39lVZB7zVzGy+HYtERAHGzmAZrLuexEyMawH5nnwDHfDONe1sU2Q==
							
						
						
							
						
					
					
						
							
								
							
							
							
								
									
										
									
								
								
								3S7TJlX5oL7dCnuCJuBKgaNCnVk=
							
							
								
									
										
									
								
								
								j8OWFlN7GQwWKrgmDeVieZ6aWLA=
							
						
						i1MA
							4JsNVDOpNK3Hee7DX58WKym6tIJdOdhxQSAaXBlXH7cjNszRf3XXMHWrn5cDqfz5/omARvMIxvjl6ZFBnNomBgBipL1jxo8JbryIi/s7RpWO1owj1azw1eYgMRtJpjw9uRL3ZGFPfTFTyT9C2SANe5JnwTCr5S6CWVEfWRh+rVQSxszX9zckun2dQXH//ljBaqmW5/6zYbZFfaVknpW7xz8khSx7Oqpj6/qciUhd+tc5hxZJ+yxlYdLvfIQii5o8Rb/Hp9iFta/dm99
							auafEhqBr/ZQm8Lz73LqxWiXnsrapxCXa0MfUDaWS/MLD4v7s5cJ9QTC103ZjsfXa7g==
						
						
							
								
							
						
					
		
	
	
		
			
			
				Umshfd2Ux6PF48P5oTRJMlX8NuIPECyY+JbQmx81q5RaKcyvSTyO8yFvlkbtR+QDriNpUgVApL3X9ZfCHejTxj
					2C3sJCNXkIbi16kcbqtkM193i5KWPXNN6EMcMcU6MXymwh/xaxQNRmZb2hJKaw+K5WEQ8dkpXxR7RwmVcJkvfsi18GEIXuIA==
				
			
		
	

Notes

• 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)
  

References:

• Metro
• Service-Side WSIT Configuration Files
• Client-Side WSIT Configuration Files
• Class KeyStore
• keytool – Key and Certificate Management Tool