Introduction

Businesses world-wide are rapidly adopting Web services, creating a requirement for a more comprehensive Web services architecture. Interoperability is a key challenge, and the Web Services Interoperability organization (WS-I) is the key player in this area. A second key challenge is Web services security, which has many aspects, including authentication, authorization, integrity, confidentiality, and reliability. Common mechanisms for securing Web services include J2EE role-based security and Secure Socket Layer (SSL). However, these mechanisms were not designed to operate on the SOAP message level. To fill this gap, IBM ®, Microsoft®, and Verisign proposed a Web services security specification and submitted it to the Organization for the Advancement of Structured Information Standards (OASIS) for evaluation. OASIS then published this specification as a working draft, and additional companies have joined the effort to create Web services security specifications. OASIS has now published three Web services security specifications:

• Web Services Security (WSS): Simple Object Access Protocol (SOAP) Message Security
• Web Services Security (WSS): Username Token Profile
• Web Services Security (WSS): X.509 Token Profile

Highlights on these specifications include authentication through XML signatures, confidentiality through XML encryption, and credential propagation through security tokens. This article will give you a brief introduction to XML signature and digital certificates. It will show you how to build and secure a Web service using the IBM Key Management tool and IBM WebSphere® Studio Application Developer V5.1 (hereafter called Application Developer).

Back to top

Web services security with XML signature

WebSphere Application Server V5.0.2 supports the key features defined in the WSS: SOAP Message Security specification, including XML signature. The WSS: SOAP Message Security specification does not specify any new XML signature syntax or algorithms, but builds on the existing XML Signature Syntax and Processing standard, and defines standard formats for attaching XML signatures to SOAP messages. XML signatures ensure the integrity of the data that they reference, and ensure that the content of the data is not tampered with. XML signatures can also be used in conjunction with security tokens (for example, X.509 certificates) to authenticate the identity of the signer/sender of a SOAP message.

XML signature

An XML signature is basically an XML fragment attached to an XML document. What makes this XML fragment so powerful is that it can be generated only with the data in the original XML document and a secret key that only the signer has access to. The following steps illustrate the XML signature procedure:

1. Identify the elements in an XML document that need to be signed.
2. For each element, apply a list of optional transformations. Transformation allows amendable data to be omitted from the computation of an XML signature. Consider a purchase order scenario -- Figure 1 shows a sample purchase order document that is processed by various departments such as sales, shipping, and so on:

   Figure 1. Sample purchase order document
   

   While processing this document, each department signs it and appends its department ID to the path element. The path element must be stripped out before computing each department's XML signature, because an XML signature will be invalidated if the original data used to compute the signature is modified, in this case, when subsequent departments append their department ID to the path element. The resulting value from the last transformation (or the contents of the original element if there is no transformation) is used to calculate a digest value.

3. A digest value is a sophisticated checksum for verifying the contents of the original element. Any change to the element contents will change the digest value. A recipient can verify the integrity of the element by re-calculating its digest value and comparing it with the digest value being sent. A mismatch indicates that the content was modified and hence cannot be trusted.
4. Figure 2 shows the XML representation of a digest value. A digest value and its related information are enclosed within a SignedInfo element:

   Figure 2. SignedInfo element
   

   Although the use of digest values ensures the integrity of an XML document, it does not prevent someone from intercepting the document, changing it, recomputing the digest value, and retransmitting the modified document. To overcome this problem, a signature value is computed based on the the SignedInfo element, and only the signer of the document can generate the correct signature value.
5. The SignedInfo element must be canonicalized (normalized) before it can be used to calculate the signature value. The canonicalization process addresses the different textual representations that an XML fragment can have. For example, differences in the way comments and whitespaces are interpreted may result in different data streams given the same fragment of XML. These variations may render an XML signature invalid even if the content is not tampered with.
6. Next, a signature algorithm is used to encrypt the result from the canonicalization process. This involves the use of a secret key that only the signer has access to. The result is the signature value. A recipient can use the signer's public key to decrypt and verify the the signature value.
7. The signature value along with the SignedInfo element are attached to the original XML document. This completes the process of creating an XML signature.
8. To verify the content of a document, decrypt the digital signature with the sender's public key. The result is a digest code which acts as a checksum for the document. Any slight changes in document will render the digest code incorrect.

Digital certificate

Digital certificate is analogy to an electronic ID. It identifies the certificate owner and delivers the owner's public key. Each certificate is issued by a Certificate Authority (CA). The following steps illustrate the basis of digital certificates.

1. Figure 3 shows a server sending a certificate request to a CA. The certificate request includes information such as:
   • The distinguished name of the server, which contains the server's common name, organization name, and so on
   • The public key of the server
   • The signature of the server

   Figure 3. Certificate request
   

2. The CA verifies the request and authenticates the server. If the server passes the verification, the CA will sign the server's public key with its own private key and issue the server a certificate that contains information from the original certificate request and the CA's signature:

   Figure 4. CA signs and issues a certificate
   

3. The server can now present this certificate to clients that require authentication. A client verifies the certificate by validating the CA's signature on the certificate. To do this, the client needs a copy of the CA's public key. Since public keys are distributed in certificates, the client needs a copy of the CA's certificate. The CA's certificate may be issued by another CA, in which case, the client needs to trust the certificate from that CA as well. Eventually, the client will reach a root CA who has a self-signed certificate.
4. Certificates can be maintained in keystore files. A keystore file contains personal certificates, signer certificates and the owner's private key. Personal certificates are certificates that you distribute to others; signer certificates are certificates that you trust. Figure 5 shows the keystores owned by each entity based on the sample scenario:

   Figure 5. Certificates owned by each entity
   

5. The setup shown in Figure 5 allows a one-way authentication, that is, the client can authenticate the server but not the other way around. To establish a mutual authentication, the client needs to acquire a certificate from a CA, and the server needs to add that CA's certificate to its keystore.

Back to top

Creating certificates and keystores

To establish a secure communication channel between a Web service and a Web service client through XML signature, you need to create digital certificates and keystores for both the server and the client. This section will show you how to do this using the IBM Key Management tool.

1. First of all, make sure the command line environment is setup correctly. Open
   <WebSphere Studio Application Developer installation directory>/runtimes/base_v5/bin/setupCmdLine.bat with a text editor. The first two lines of code should read something like this:

   SET WAS_HOME=<WebSphere Studio Application Developer installation directory>\runtimes\base_v5 SET JAVA_HOME=<WebSphere Studio Application Developer installation directory>\runtimes\base_v5\java

   
   
2. To launch the IBM Key Management tool, open a command prompt and navigate to the
   <Application Developer installation directory>/runtimes/base_v5/bin directory. Run the ikeyman.bat command. Figure 6 shows the IBM Key Management tool:

   Figure 6. IBM Key Management tool
   

3. Create the server's keystore. Select Key Database File => New.
4. Figure 7 shows the new key database file dialog. Make sure JKS is selected as the key database type. Enter server_keystore.jks as the file name and enter any location on your file system. Click OK. In the password dialog, enter server123 as the password and click OK:

   Figure 7. Creating the server's keystore
   

5. Delete all the signer certificates that are automatically added to the keystore. Some of these certificates have expired and will cause problems if you don't remove them. Click Delete to remove the selected certificate.
6. Instead of sending a certificate request to a real CA, the server will play the role of a CA and create a self-signed certificate. Select Personal Certificates in the drop down and click on New Self-Signed:

   Figure 8. Creating a self-signed certificate
   

7. Figure 9 shows the create new self-signed certificate dialog. In this dialog, enter echo_ws as the key label. Make sure X.509 V3 and 1024 are selected as the version and key size, respectively. Enter your organization name. Click OK:

   Figure 9. Create new self-signed certificate dialog
   

8. Extract the echo_ws certificate to your file system. You will import it as a signer certificate into the client's keystore later. In order for the client to verify the echo_ws certificate, the client needs to have the public key of the CA who signed this certificate. In this case, it would be the server because the server is also playing the role of the CA. That means the client needs to import the server's certificate as a signer certificate. To extract the echo_ws certificate, click on Extract Certificate. Make sure Base64-encoded ASCII data is selected as the data type, enter server.arm as the certificate file name, enter any location, and click OK:

   Figure 10. Extracting the server's certificate
   

9. Next, create the client's keystore file. Select Key Database File => New..
10. Select JKS as the key database type, enter client_keystore.jks as the file name, enter any location and click OK. In the password dialog, enter client123 as the password and click OK.
11. Again, delete all the signer certificates that are automatically added to the keystore.
12. Import the server's certificate as a signer certificate to the client's keystore. Click Add, browse for server.arm, and click OK (see Figure 11). You will be prompted to enter a label for this certificate. Enter echo_ws as the label name and click OK:

    Figure 11. Adding the server's certificate to the client's keystore
    

13. You will now create a certificate for the client. The client will also play the role of a CA and create a self-signed certificate. Select Personal Certificates in the drop down and click New Self-Signed. In the create new self-signed certificate dialog, enter echo_client as the key label. Make sure X509 V3 and 1024 are selected as the version and key size, respectively. Enter your organization name and click OK.
14. Extract the Echo Web service client certificate to your file system. You will import it as a signer certificate into the server's keystore. Click on Extract Certificate, make sure Base64-encoded ASCII data is selected as the data type, enter client.arm as the certificate file name, enter any location, and click OK.
15. Open the server's keystore. Select Key Database File => Open.
16. Browse to server_keystore.jks and click OK. You will be prompted for the server keystore's password. Eenter server123 and click OK.
17. Import the client's certificate as a signer certificate to the server's keystore. Select Signer Certificates in the drop down, click Add, browse to client.arm, and click OK. Enter echo_client as the label name and click OK. Figure 12 shows the result:

    Figure 12. Adding the client's certificate to the server's keystore
    

18. You have successfully created the keystores and certificates you needed for this tutorial. You can now close the IBM Key Management tool. Figure 13 summarizes the keystores and certificates that you have created in this section:

    Figure 13. Summary of the keystores and certificates created in this section
    

Back to top

Building the Echo Web service and Web service client

This section guides you through the steps to create a Web service and a Web service client from an Echo Java™ bean. Create a file named Echo.java with the following contents:

package ws;

public class Echo
{
   public String echo(String s)
   {
      return s;
   }
}

1. Start WebSphere Studio.
2. Create a Web project. Select File =>New => Other.
3. Select Web from the menu on the left and select Dynamic Web Project from the list on the right. Click Next.
4. Figure 14 shows the new Web Project Wizard. Enter EchoService as the project name and click Finish:

   Figure 14. New Web Project Wizard
   

5. Import the Echo Java bean into the Web project. Select File => Import.
6. Select File system and click Next.
7. Browse to the directory where you created Echo.java, select it, and enter EchoService/JavaSource/ws in the Into folder text field. Click Finish:

   Figure 15. Import Echo.java
   

8. Launch the Web Service Creation Wizard. Select File => New => Other.
9. Select Web services from the menu on the left and select Web service from the list on the right. Click Next.
10. Figure 16 shows the Web Services Creation Wizard. Choose Java bean Web Service as the Web service type. Select the Generate a proxy, Test the generated proxy and Overwrite files without warning checkboxes. Click Next:

    Figure 16. Web Services Wizard
    

11. Use the default options defined in the Service Deployment Configuration page and click Next.
12. In the Web Service Java Bean Selection page, enter ws.Echo as the class name of the Java bean. Click Finish.

You have successfully created the Echo Web service and Web service client. The next sections will show you how to configure them to use XML signature.

Back to top

Securing the Echo Web service and Web service client

Since the WSS: SOAP Message Security, and WSS: Username Token Profile have not been finalized yet, there is no standard format for configuring XML signature in the standard JSR-109 deployment descriptors. The support for XML signature is provided through IBM extensions to the JSR-109 deployment descriptors. The Web Services Editor and Web Services Client Editor provide a very convenient way to edit these deployment descriptors.

Signing the SOAP request

The Web Services Client Editor allows you to specify the key for signing the client SOAP request.

1. Navigate to the EchoServiceClient/WebContent/WEB-INF directory in the WebSphere Studio workbench and double click on webservicesclient.xml to bring up the Web Services Client Editor.
2. Click on the Security Extensions tab. Figure 17 shows the security extension page of the Web Services Client Editor:

   Figure 17. Web Services Client Editor's Security Extensions page
   

3. Expand the Request Sender Configuration => Integrity section. Click Add, select body as the Reference Part, and click OK:

   Figure 18. Integrity
   

4. Click on the Port Binding tab to bring up the port binding page.
5. In the Security Request Sender Binding Configuration => Key Locators section, click Add. A key locator specifies the repository to use for retrieving keys.
6. Figure 19 shows the Key locator dialog. Enter the necessary information. Substitute the keystore path with the location of the client_keystore.jks file. If you have chosen to use your own password instead of client123 for the client keystore, enter that in the key store storepass and the key pass column. Click OK:

   Figure 19. Key locator dialog
   

7. In the Security Request Sender Binding Configuration => Signing Information section, click Enable. Signing information in this case determines the key for signing outgoing SOAP messages.
8. Figure 20 shows the Signing information dialog. Enter the necessary information and click OK:

   Figure 20. Signing information dialog
   

9. Save the Web Services Client Editor.

Authenticating the server response

The Web Services Client Editor also allows you to verify the integrity of the SOAP response message and to authenticate the sender of the response.

1. In the Web Services Client Editor, click on the Security Extensions tab.
2. In the Security Extensions page, expand the Response Receiver Configuration => Required Integrity section. Click Add, select body as the Reference Part, and click OK.
3. Click on the Port Binding tab. In the Security Response Receiver Binding Configuration => Certificate Store List => Collection Certificate Store section, click on Add. A certificate store contains a list of certificates that will be used to validate incoming X.509 security tokens.
4. Figure 21 shows the Collection certificate store dialog. Enter the necessary information and click OK:

   Figure 21. Collection certificate store dialog
   

5. In the Security Response Receiver Binding Configuration => Trust Anchor section, click Add. A trust anchor specifies a list of keystores that contain certificates from trusted CAs.
6. Figure 22 shows the Trust anchor dialog. Enter the necessary information and click OK:

   Figure 22. Trust anchor dialog
   

7. In the Security Response Receiver Binding Configuration => Signing Information section, click Add. Signing information in this case determines the certificate to use for validating incoming SOAP messages.
8. Figure 23 shows the Signing information dialog. Enter the necessary information and click OK:

   Figure 23. Signing information dialog
   

9. Save the Web Services Client Editor.

Signing the SOAP response

Continuing with the scenario, you will use the Web Services Editor to specify the key for signing the server SOAP response.

1. Navigate to the EchoService/WebContent/WEB-INF directory and double-click on webservices.xml to bring up the Web Services Editor.
2. Click on the Security Extensions tab. Expand the Response Sender Service Configuration Details => Integrity section. Click Add, choose body as the Reference Part, and click OK.
3. Click on the Binding Configurations tab. In the Response Sender Binding Configuration Details => Key Locators section, click Add.
4. Figure 24 shows the Key locator dialog. Enter the necessary information and click OK:

   Figure 24. Key locator dialog
   

5. In the Response Sender Binding Configuration Details => Signing Information section, click Enable.
6. Figure 25 shows the Signing information dialog. Enter the necessary information and click OK:

   Figure 25. Signing information dialog
   

7. Save the Web Services Editor.

Authenticating the client request

The Web Services Editor also allows you to verify the integrity of the client SOAP request and to authenticate the sender of the request.

1. In the Web Services Editor, click on the Security Extensions tab.
2. In the Security Extensions page, expand the Request Receiver Service Configuration Details => Required Integrity section. Click Add, choose body as the Reference Part, and click OK.
3. Click on the Binding Configurations tab. In the Request Receiver Service Configuration Details => Certificate Store List => Collection Certificate Store section, click Add.
4. Figure 26 shows the Collection certificate store dialog. Enter the necessary information and click OK:

   Figure 26. Collection certificate store dialog
   

5. In the Request Receiver Service Configuration Details => Trust Anchor section, click Add.
6. Figure 27 shows the Trust anchor dialog. Enter the necessary information and click OK:

   Figure 27. Trust anchor dialog
   

7. In the Request Receiver Service Configuration Details => Signing Information section, click Add.
8. Figure 28 shows the Signing information dialog. Enter the necessary information and click OK:

   Figure 28. Signing information dialog
   

9. Save the Web Services Editor.

The Echo enterprise application must be restarted before the changes to the deployment descriptors take effect.

1. Open the server perspective. Click on the menu Window => Open Perspective => Others.
2. Select Server and click OK.
3. In the Servers view, right click on the server that the Echo enterprise application is deployed to => Restart Project => DefaultEAR.

Back to top

Testing the Echo Web service

When the sample JSPs are generated, by default, they use the Java 2 Standard Edition (J2SE) approach to instantiate the client stub. The J2SE approach is solely based on the programming models defined by JAX-RPC. This means the client stub object has no knowledge of the configuration defined in the JSR-109 deployment descriptors, for example, XML signature configuration. In order to take advantage of the deployment configurations, JSR-109 requires the client stub to be instantiated from a Service Interface that is available via a JNDI lookup. Therefore, you have to modify the generated sample JSPs to use JNDI lookup instead of the default J2SE approach. The steps below show you how this can be done.

Tip: If you are using WebSphere Studio V5.1.1, you can skip Steps 1 and 2.

1. Navigate to the EchoServiceClient/WebContent/sample/Echo folder, right-click, and select Result.jsp => Open With => Text Editor.
2. Modify Result.jsp as shown in Figure 29. Save and close the text editor.

   Figure 29. Result.jsp
   

3. Right click on TestClient.jsp => Run on Server.
4. Select the server that the Echo Web service client is deployed to, click Finish.
5. Click on the echo(java.lang.String) method, enter Hello World in the input text field and click Invoke. The result is displayed in the Result pane. See Figure 30 for details:

   Figure 30. Invoking the Echo Web service
   

   Figures 31 and 32 show the SOAP request and response captured in the TCP/IP Monitoring Server. The XML signatures of the client and the server are attached to the SOAP request header and SOAP response header, respectively:

   Figure 31. SOAP request
   

   Figure 32. SOAP response
   

Back to top

Conclusion

This article provided an introduction of XML signature and digital certificate. It discussed how to build a secure Web service through XML signature using IBM Key Management tool and WebSphere Studio V5.1. XML signature allows you to verify the integrity of a message and to authenticate the sender of the message. It is one of the many ways to protect your Web service. Other mechanisms for securing a Web service will be covered in other articles of this series.

Resources

• Java API for XML-based Remote Procedure Call (JAX-RPC)
  
  
• Java Specification Request 109 (JSR-109)
  
  
• OASIS Web Services Security technical committees
  
  
• Organization for the Advancement of Structured Information Standards (OASIS)
  
  
• Simple Object Access Protocol (SOAP)
  
  
• Web Service Description Language (WSDL)
  
  
• Web Services Interoperability (WS-I)
  
  
• XML Signature Syntax and Processing
  
  

About the author

Comments (Undergoing maintenance)

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Web services security with XML signature
• Creating certificates and keystores
• Building the Echo Web service and Web service client
• Securing the Echo Web service and Web service client
• Testing the Echo Web service
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

With the no-charge DB2 Express-C, pureXML, Zend Core PHP, and Java you can develope advanced Web 2.0 applications quickly that matter.

---

• Try: Download a free trial version of DB2 Express-C, which includes Zend Core PHP and pureXML technology that is ideally suited for managing both XML and relational data.
• Article: See how DB2 pureXML schema capabilities can evolve schemas without making any changes to your applications.
• Tutorial: This tutorial shows you how to use DB2's pureXML to expose the native XML capabilities of DB2.
• Buy: DB2 9 for Linux, UNIX and Windows

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers