Secure Web services: Interoperability

Skill Level: Intermediate Hedley Proctor Software engineer IBM

23 Feb 2004 Learn how to use WS-Security to demonstrate secure interoperability between a .NET client and a Java Web service.

Section 1. Tutorial tips

Should I take this tutorial?
This tutorial is designed for people who have basic knowledge of Web services and associated technologies, such as WSDL and SOAP, who want to learn how to construct a Java Web service with a Microsoft Visual Basic .NET client for it that communicates securely using WS-Security. I begin by using basic authentication and then move on to digital signature and its use for authentication. The development tools I used to create and run the Web service were: IBM(R) WebSphere(R) Studio Application Developer V5.1.0 (Application Developer) and Microsoft Visual Studio .NET 2003 with Web Services Enchancements 1.0 SP1. All my WebSphere work was done on a Microsoft Windows 2000 operating system and the Visual Basic .NET work was done on Microsoft Windows XP. I assume that you have some knowledge of security certificates, what authentication means and how digital signatures are created, although I do give brief explanations. I also assume basic knowledge of IBM WebSphere Application Server, such as being able to turn on security and select user registries. If you would like to take the tutorial but feel unsure about any of these subjects, the resources section has links to appropriate documentation.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 1 of 35

developerWorks

ibm.com/developerWorks

Getting help
For technical questions about the content of this tutorial, contact the author, Hedley Proctor, at proctor@uk.ibm.com.

Uses of basic authentication and digital signature

Basic authentication is a method whereby a user sends a username and password to a server. You will see how to construct a Java Web service that uses basic authentication and invoke it using a Visual Basic .NET client. The major concern when using basic authentication to invoke a Web service is that the password is sent unencrypted in the SOAP message. While transport-level encryption can be used by sending the message via https, message level encryption is not used. Security can be improved by sending a digest of the password, but there is still an outstanding problem: a third party could alter the message while it is in transit. The username and password would still be correct at the other end, so the recipient would not know. Digital signatures not only let you use message-level encryption, but also ensure that a message cannot be tampered with, and hence provide a much more secure means of authenticating a user. When clients digitally signs their message, they use a hash algorithm to create a digest of the message, which they then encrypt using their private key. They include this encrypted digest and their public key with the message. When the server receives the message, they use the public key to decrypt the digest. The server then compares this with its own hash of the message body. If the two digests match, the server knows two things: 1. 2. The message body has not been tampered with. The message must have come from the person who claims to have sent it.

You can use XML Digital Signature purely to ensure that messages reaching your Web service are not tampered with, or as a means of authentication. Due to constraints of space, I only have time to do the former in this tutorial. However, I give some pointers as to how you would extend the example to use digital signature for authentication. Standards for interoperable Web services have been developed by the Web Services Interoperability Organisation (WS-I.org). However, the most important security document is the WS-Security specification, which pre-dates the WS-I. Both .NET and Application Developer base their implementations on it. If you wish to read the specification, the section contains a link to it.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 2 of 35

ibm.com/developerWorks

developerWorks

Steps in this tutorial

This tutorial shows you how to: 1. 2. 3. 4. 5. Create a simple online bookstore Web service in Application Developer, starting from a WSDL, and configure it for basic authentication. Create and test a .NET client that invokes this Web service. Create a new version of the same Web service using the default security settings for XML Digital Signature with a test Java client. Configure the server security settings so that you can use different security certificates. Construct a .NET client, configure it to use your own certificate, and use it to invoke the Web service.

Afterwards, I summarize the important points to remember when using Web Services authentication and digital signature.

Section 2. Basic authentication: Java Web service

Examining the WSDL
1. 2. Start up WebSphere Studio Application Developer. Click on File --> New --> Dynamic Web Project. You will create two Web services during this tutorial, one for basic authentication and one for digital signature. Call this first project "bookstoreAuth". Expand the project directory, right click on the WebContent directory and select Import from the context menu. Then select File System. Browse to the directory that contains the WSDL and the OrderBookBindingImpl.java file and import them both into the WebContent directory. (It doesn't really matter which directory of the project you put them in since both of them will be moved later.)

3.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 3 of 35

developerWorks

ibm.com/developerWorks

Have a quick look at the WSDL. It is written in document form with a literal binding style. It is a very simple WSDL, but will suffice for what you want to do. The client sends in a message to the online bookstore for a book it wants to purchase. The implementation of the Web service will write this book title to a log file along with the time. Obviously in a more realistic situation, far more information would be sent, such as quantity, dispatch to address, credit card details, etc.

Creating the Web service

1. 2. Start the Web services wizard by clicking on File --> New --> Other --> Web Services --> Web Service. On the Web Services page: select Skeleton Java bean Web Service as the Web service type. Click Next. Figure 1. Create skeleton Java bean Web service

3.

On the Service Deployment Configuration page: set the Service Web Project to be the dynamic Web project you created. You also need to choose a server. I used a WebSphere Application Server V5.0.2 Test
Trademarks Page 4 of 35

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

ibm.com/developerWorks

developerWorks

server, but you may wish to use a non-test server. 4. 5. On the Web Service Selection page: browse to the WSDL and select it. Click Next. On the Web Service Skeleton Java Bean Configuration page: you do not want either of the default security settings -- XML Digital Signature or XML Encryption -- so just click Next. On the Web Service Publication page: leave both of the publication options unchecked. Click Finish.

6.

This creates the skeleton implementation of the Web service. You need to replace the skeleton implementation file with the actual business logic: Replace the OrderBooksBindingImpl.java file in the JavaSource directory of your Web service with the implementation file that you imported earlier. This will produce an error in the console window, because you need to make sure that this change is mirrored on the server. I will show you how to fix this later.

Configuring for basic authentication

1. 2. Expand the bookstoreAuth --> WebContent --> WEB-INF folder and open the webservices.xml file. This produces a number of pages, identified by tabs at the bottom. Select the Security Extensions tab. Figure 2. Configuring security extensions for basic authentication

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 5 of 35

developerWorks

ibm.com/developerWorks

3.

On the right side of this page, you can see two sets of configuration settings -- Request Receiver Service Configuration Details and Response Sender Service Configuration Details. The request receiver settings determine how the server treats incoming messages; the response sender settings govern the format of the messages it sends back. Expand the Request Receiver Service Configuration Details --> Login Config and click Add. Set the authentication method to BasicAuth and click on OK. Select the Binding Configurations tab. On the right side of this page, you again have two sets of configuration settings -- Request Receiver Binding Configuration Details and Response Sender Binding Configuration Details. Expand the Request Receiver Binding Configuration Details --> Login Mapping section and click Add. Enter the following details: Authentication method: BasicAuth Configuration name: WSLogin

4. 5. 6. 7.

8.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 6 of 35

ibm.com/developerWorks

developerWorks

Callback Handler Factory Class Name: com.ibm.wsspi.wssecurity.auth.callback.WSCallbackHandlerFactoryImpl 9. Save the webservices.xml file.

You now have the correct settings for authentication, so you can restart the project on the server. (Remember that since you are using security, I am assuming that security is enabled. If it isn't, double click on the server and change the settings in the Security tab.) Right click on the server and select Restart project --> DefaultEAR. Since you are going to be authenticating by using a username and password, you can either use a username which already exists on your system, or you can create a new one just for this example. (Remember to delete it afterwards.) I created a new Windows user called client1 with a password of booksforme.

Setting up a TCP Monitor

You could run the Web service like this. However, you'll find it helpful to examine the SOAP message being sent, so let's set up a TCP monitoring server. This monitor will accept SOAP messages on one port and send them on on another. 1. 2. 3. Select the Servers tab in the bottom pane. Right click and select New --> Server and Server Configuration. Set the server type to Other --> TCP/IP Monitoring Server and give the server a name. Click Finish. Figure 3. Creating a TCP Monitor

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 7 of 35

developerWorks

ibm.com/developerWorks

4.

When the server appears in the server pane, right click on it and select Start.

Section 3. Basic authentication: .NET client

Setting up the references
You are now ready to create the .NET client. 1. 2. Start Visual Studio .NET. Create a new Visual Basic .NET project. Select the Windows Application type and call it SecureInteropsAuth. This brings up a blank Windows form.
Trademarks Page 8 of 35

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

ibm.com/developerWorks

developerWorks

Figure 4. Creating SecureInteropsAuth .NET Project

3. 4.

Expand the project and right click on References. Select Add Reference. Scroll down the list of .NET references and highlight Microsoft.Web.Services.dll. Click Select and then OK. You should see the reference added to your project. Figure 5. Adding reference to Microsoft.Web.Services.dll

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 9 of 35

developerWorks

ibm.com/developerWorks

5. 6.

Right click on References again and select Add Web Reference. Assuming your Web service is running on the same machine, the location of the WSDL file will be http://localhost:9080/bookstoreAuth/wsdl/com/onlinebookstore/www/bookstore.wsdl since bookstoreAuth was the name of the dynamic Web project you created and www.onlinebookstore.com was the namespace of the WSDL. Type this into the URL box and press return. This should give a description of the OrderBookService as having one method, OrderBook. Change the name of the reference to bookstoreAuth and click on Add Reference. This generates a number of code stubs in your project, which can be seen using the class view. Expand the class view until you see the OrderBookService class and double click on it to open it in the editor. You need to change this class to use the Web Services Enhancements code, rather than the older Web services code. Change it so that rather than inheriting from System.Web.Services.Protocols.SoapHttpClientProtocol it inherits from Microsoft.Web.Services.WebServicesClientProtocol. You also want to look at the client messages using the TCP monitor, so

7.

8.

9.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 10 of 35

ibm.com/developerWorks

developerWorks

change the port number in the address from 9080 to 9081. Then close the OrderBookService code window.

Creating the form

1. Back on the form, you will need a text box to input the name of the book and a button to invoke the Web service. It will also be useful to have a button to clear the text box so that you can input a different book name; so add one text box and two buttons to the form. With a default Visual Studio .NET configuration, you should have a pane in the lower left section of the screen showing the form properties. Select the text box with the mouse and the list should change to show the text box properties. Scroll down until you see the name property. Change the name to Input. Then change the text property so that it is empty. Change the name of one button to InvokeWebService and the text to Invoke Web Service. Change the name of the other button to ClearTextBox and the text to Clear Text Box.

2.

3. 4.

Your form should now look like this: Figure 6. Form with one text box and two buttons

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 11 of 35

developerWorks

ibm.com/developerWorks

Writing the code

Right click on the form and select View Code from the menu. Add the following import statements to the top of the code window, above the class definition:
Imports Microsoft.Web.Services Imports Microsoft.Web.Services.Security

In the code for invoking the Web service you need to add the username and password to its SOAP message before invoking the Web service. In addition, by default, .NET requires its path header to be processed. You don't want to process it, so set its mustUnderstand attribute to false. The code needs to be run when the InvokeWebService button is clicked, so use the two drop down boxes at the top of the code window to select InvokeWebService as the object and Click as the method respectively. Then insert the following code:
Dim WebService As New bookstoreAuth.OrderBookService WebService.RequestSoapContext.Path.MustUnderstand = False Dim myUsernameToken As New UsernameToken("client1", "booksforme", PasswordOption.SendPlainText) WebService.RequestSoapContext.Security.Tokens.Add(myUsernameToken) WebService.orderBook(Input.Text)

You also need to implement the Click method of the ClearTextBox object to say:
Input.Clear()

Running the .NET client

1. 2. To run the .NET client from within Visual Studio, select the project, right click and select Debug --> Start New Instance. Type the name of a book into the box and click Invoke Web Service.

Figure 7. Running .NET basic authentication client

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 12 of 35

ibm.com/developerWorks

developerWorks

In Application Developer, select the TCP/IP Monitor tab on the lower pane and then double click on the title bar of the window to maximize it. (If the TCP/IP Monitor view is not on the screen, you can display it by selecting Window --> Show View --> Other --> Server --> TCP/IP Monitor.) The SOAP message should look like this (edited to be readable):
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Header> <wsrp:path soap:actor="http://schemas.xmlsoap.org/soap/actor/next" xmlns:wsrp="http://schemas.xmlsoap.org/rp"> <wsrp:action></wsrp:action> <wsrp:to> http://localhost:9081/bookstoreAuth/services/OrderBook </wsrp:to> <wsrp:id> uuid:8efe1ef6-94a2-4027-b4a2-ede6d4e3ace2 </wsrp:id> </wsrp:path> <wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> <wsu:Created>2003-12-09T12:38:41Z</wsu:Created> <wsu:Expires>2003-12-09T12:43:41Z</wsu:Expires> </wsu:Timestamp> <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"> <wsse:UsernameToken xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility" wsu:Id="SecurityToken-27ce429e-8684-4bc3-a2ea-658215907037"> <wsse:Username>client1</wsse:Username> <wsse:Password Type="wsse:PasswordText"> booksforme </wsse:Password> <wsse:Nonce>Tjz1NHajlYVe/ro0VuGtVA==</wsse:Nonce> <wsu:Created>2003-12-09T12:38:41Z</wsu:Created> </wsse:UsernameToken> </wsse:Security>

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 13 of 35

developerWorks

ibm.com/developerWorks

</soap:Header> <soap:Body> <bookTitle xmlns="http://www.onlinebookstore.com"> Madame Bovary</bookTitle> </soap:Body> <lt;/soap:Envelope>

Section 4. Digital signature: Java Web service

Creating the Web service
You have seen how to carry out basic authentication between a .NET client and a Java Web service. However, if you want a more secure method of authentication, digital signature is a better choice. You can begin by quickly creating a Java Web service and client with the default settings for digital signature, just to familiarize yourself with the setup. Then I will explain how to configure the security settings for the general case, and you can create a .NET client that uses your own security certificates. 1. Create a new dynamic Web project and call it bookstoreDsig. Figure 8. Creating bookstoreDsig project

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 14 of 35

ibm.com/developerWorks

developerWorks

2. 3. 4.

Import the WSDL and the OrderBookBindingImpl.java file into the WebContent directory, as before. Start the Web services wizard by clicking on File --> New --> Other --> Web Services --> Web Service. On the Web Services page: select Skeleton Java bean Web Service as the Web service type. Select Generate a proxy and Test the generated proxy. Click Next. Figure 9. Create skeleton Java bean digital signature Web service

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 15 of 35

developerWorks

ibm.com/developerWorks

5.

On the Service Deployment Configuration page: set the Service Web Project to be the dynamic Web project you created. The client must run in a different Web archive, so set the Client Web Project to a different name. Click Next. Figure 10. Service Deployment Configuration page

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 16 of 35

ibm.com/developerWorks

developerWorks

6. 7.

On the Web Service Selection page: browse to the WSDL and select it. Click Next. On the Web Service Skeleton Java Bean Configuration page: change the Security configuration to XML Digital Signature. Click Next. This will bring up a warning dialog box saying that a WS-I Incompliance has been detected. This is simply because the WS-Security specifications had not been finalized when this wizard was written, so it would have been impossible to claim conformance. Click Ignore all. On the Web Service Proxy page: it should already say XML Digital Signature, so click Next. On the Web Service Client Test page: the orderBook method is the only one available, and it should be selected, so click Next.
Trademarks Page 17 of 35

8. 9.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

developerWorks

ibm.com/developerWorks

Figure 11. Create skeleton Java bean digital signature Web service

10. On the Web Service Publication page: leave both of the publication options unchecked. Click Finish. This should bring up a browser window with three panes: Methods, Inputs, and Results. However, you still need to do a couple of things before testing your Web service: Replace the OrderBooksBindingImpl.java skeleton file in the JavaSource directory of your Web service with the implementation file that you imported earlier. As before, this will produce an error in the console window, that you can fix in a minute.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 18 of 35

ibm.com/developerWorks

developerWorks

Ensure you have TCP Monitor running. To make the client messages go via the monitor, expand the JavaSource directory of the client and open up the OrderBookServiceLocator.java file. The address of the Web service will say http://localhost:9080/bookstoreDsig/services/OrderBook. Change the port number to 9081 and save the file. To ensure that the server picks up the changes to your Web service and client projects, select the Servers tab, right click on the server and select Restart project --> DefaultEAR.

Testing the Web service

Now you are ready to test the Web service: 1. 2. 3. Close the client browser window that is open. Expand the client Web project --> WebContent --> Sample --> OrderBookPortType. Right click on TestClient.jsp and select Run on server. (It doesn't matter whether you select via TCP/IP monitor from the dialog box, since the client will pick up the port number for the service from the file you have just changed.) The Server Selection dialog box should have the correct server selected, so click Finish. In the Select a Server Client dialog box, choose Web Browser. Click Finish.

4. 5.

This brings up the jsp with three panes again: Figure 12. Client test

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 19 of 35

developerWorks

ibm.com/developerWorks

Select the orderBook method. Type a book title into the input box and hit return. The results pane will go blank, but you can examine the SOAP messages using the TCP monitor. Select the TCP/IP Monitor tab on the lower pane and then double click on the title bar of the window to maximize it. The message should look like this:
<soapenv:Envelope xmlns:soapenc="http://schemas.xmlsoap.org/soap/encoding/" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <soapenv:Header> <wsse:Security xmlns:wsse="http://schemas.xmlsoap.org/ws/2003/06/secext" soapenv:actor="myActorURI" soapenv:mustUnderstand="1"> <wsse:BinarySecurityToken xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility" EncodingType="wsse:Base64Binary" ValueType="wsse:X509v3" wsu:Id="wssecurity_binary_security_token_id_6964294951763779534"> MIIDQTCCAqqgAwIBAgICAQQwDQYJKoZIhvcNAQEFBQAwTjELMAkGA1UEBhMCSlAxETAP BgNVBAgTCEthbmFnYXdhMQwwCgYDVQQKEwNJQk0xDDAKBgNVBAsTA1RSTDEQMA4GA1UE AxMHSW50IENBMjAeFw0wMTEwMDEwOTU0MDZaFw0xMTEwMDEwOTU0MDZaMFQxCzAJBgNV BAYTAkpQMREwDwYDVQQIEwhLYW5hZ2F3YTEMMAoGA1UEChMDSUJNMQwwCgYDVQQLEwNU UkwxFjAUBgNVBAMTDVNPQVBSZXF1ZXN0ZXIwgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJ AoGBAMy3PfZ1mPhrEsBvYiOuIlPV3Uis5Yy6hmxo2YwYC2nNDBPzKslWUi/Q+fK+DNdY 6KEHmuDrcVcEma48J9X1a5avRlksQfKptKoVn4eBys2i/wkwyzQhDaFji79/MvnTRW8E Vy99FNKw4PFnhOoe1tlDcNBuIH/fIuGOz9ElTV+fAgMBAAGjggEmMIIBIjAJBgNVHRME AjAAMAsGA1UdDwQEAwIF4DAsBglghkgBhvhCAQ0EHxYdT3BlblNTTCBHZW5lcmF0ZWQg Q2VydGlmaWNhdGUwHQYDVR0OBBYEFIW3FD1cXie4j4zw1gAp4cuOAZ4lMIG6BgNVHSME gbIwga+AFL35INU4+WRy09vaf9zOsP7QvO9voYGSpIGPMIGMMQswCQYDVQQGEwJKUDER MA8GA1UECBMIS2FuYWdhd2ExDzANBgNVBAcTBllhbWF0bzEMMAoGA1UEChMDSUJNMQww CgYDVQQLEwNUUkwxGTAXBgNVBAMTEFNPQVAgMi4xIFRlc3QgQ0ExIjAgBgkqhkiG9w0B CQEWE21hcnV5YW1hQGpwLmlibS5jb22CAgEBMA0GCSqGSIb3DQEBBQUAA4GBAHkthdGD gCvdIL9/vXUo74xpfOQd/rr1owBmMdb1TWdOyzwbOHC7lkUlnKrkI7SofwSLSDUP571i iMXUx3tRdmAVCoDMMFuDXh9V7212luXccx0s1S5KN0D3xW97LLNegQC0/b+aFD8XKw2U

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 20 of 35

ibm.com/developerWorks

developerWorks

5ZtwbnFTRgs097dmz09RosDKkLlM </wsse:BinarySecurityToken> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> </CanonicalizationMethod> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1"> </SignatureMethod> <Reference URI="#wssecurity_body_id_8792741222646703397"> <Transforms> <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"> <ec:InclusiveNamespaces xmlns:ec="http://www.w3.org/2001/10/xml-exc-c14n#" PrefixList="xsd #default soapenc soapenv xsi wsu "> </ec:InclusiveNamespaces> </Transform> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1"> </DigestMethod> <DigestValue>0a7cNW/eTNHMEUZWGFS2Tb0ZtnU=</DigestValue> </Reference> </SignedInfo> <SignatureValue> AQjWhdVuyDV2yeHksLZM0n4LpTgw1Hf2KYeNjHggpiZDzAGvI6vwLMgqLGVC 6DbKhQmc0wJ6nX3Wm4c+Gykoi0eNkPyaGC/9b/YW0nHqr7WPuOyl9d3PpcoD uUk8Ll49obcUkFspaDt+QC5F9UHuhRtgPAZItqlaxwbFg/Y/+6g= </SignatureValue> <KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI="#wssecurity_binary_security_token_id_6964294951763779534"> </wsse:Reference> </wsse:SecurityTokenReference> </KeyInfo> </Signature> </wsse:Security> </soapenv:Header> <soapenv:Body xmlns:wsu="http://schemas.xmlsoap.org/ws/2003/06/utility" wsu:Id="wssecurity_body_id_8792741222646703397"> <bookTitle xmlns="http://www.onlinebookstore.com"> Lord of the Rings </bookTitle> </soapenv:Body> </soapenv:Envelope>

If you examine the message you can see the basic elements - the public key at the top, the canonicalization and signature methods, the digest, the signature and finally the message body. As you can see, the message body is "signed" by being cross referenced to the security information in the header. You can verify that the Web service has worked by examining the Bookstore.log file, which by default is written to the root directory of your Application Developer installation. The file should look similar to the following:
---Bookstore.log--Time: Thu Dec 11 14:48:47 GMT 2003 Order placed for: Lord of the Rings

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 21 of 35

developerWorks

ibm.com/developerWorks

Section 5. Using your own security certificates

Introduction
With your current Web service, you have used the default security settings for XML Digital Signature. This makes it easy to generate an XML Digital Signature Web service, because the wizard configures all the settings, including using sample certificates. But what do you do if you want to use your own security certificates? In order to generate a digital signature, a digest of the data in a message is created and a private key certificate is used to encrypt this digest. When the message arrives at the server, the server unencrypts the digest using the public key and compares it to its own calculation of what the digest should be. If they agree, the server knows that the message can only have come from the holder of that particular private key. In a realistic scenario, the private/public keys would be part of a certificate chain that would end in a root certifcation authority (CA). In addition to this, the certificates used by the .NET client have to be in a standard Windows format, such as PKCS, whereas those used by the Java Web service need to be in either JKS or JCEKS. (The section contains links to articles that explain the different types of security certificates.) In order to simulate this situation, I have supplied two certificates, which I created with SimpleCA -- essentially a wrapper to OpenSSL: 1. 2. A PKCS12 certificate containing a private key, that the .NET client will use. A root CA certificate that is needed to certify the above certificate.

Note that the server does not have to have the public key itself, since that is included in the message. However, it does need to be able to trust the public key, so it needs the root CA certificate for it.

Installing the certificates for the .NET client

1. 2. To manage certificates under Windows, click Start --> Run and type in mmc. Usually, within the main window, a console window will be open. If not, click File --> New.
Trademarks Page 22 of 35

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

ibm.com/developerWorks

developerWorks

3.

Click Console --> Add/Remove Snap-in... Figure 13. Add/remove certificates snap-in

4. 5. 6. 7.

Click on Add and select Certificates from the list. Accept the default of managing certificates for your use account and click Finish. Close the Add Standalone snap-in dialog box and click on OK in the Add/Remove Snap-in... dialog. Expand the Certificates - Current User list and you can see the various certificate stores and the certificates they contain.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 23 of 35

developerWorks

ibm.com/developerWorks

Figure 14. Certificate store

8.

You can now add your private key certificate to the Personal store and the root CA certificate to the Trusted Root Certification Authorities store. Double click on the interops-root.cer file. Click Install Certificate...

9.

10. Allow the wizard to select which store to add the certificate to and it should correctly select the Trusted Root Certification Authorities store. 11. Double click on the interops-dsig.p12 certificate and use the wizard to add it to the Personal store. When it prompts you for the private key password, enter interops. Again it should select the correct store automatically.

Configuring the server security settings

When the message from the client is received at the server, it includes the public key to unencrypt the digest. However, the server needs to know that this public key really is the public key for the person sending the message -- otherwise anyone could have signed the message and included their own public key. It does this by

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 24 of 35

ibm.com/developerWorks

developerWorks

having the root CA certificate for the public key in its Trust Anchor set of certificates. You know from setting up basic authentication that all the server security settings are configured in the webservices.xml file, under the "Security Extensions" and "Binding Configuration" tabs. Let's have a look at what settings are needed for digital signature: Expand your bookstore project and open the webservices.xml file. Open the Security Extensions tab. Expand Request Receiver Service Configuration Details --> Required Integrity Figure 15. Security Extensions tab

The word body should be listed in the Required Integrity box. This means that all messages coming into the server must have a digitally-signed SOAP body. If you click on Add you will see that you can also require the timestamp or security token to be signed. So how does the server verify signed data? Select the "Binding Configuration" tab. Figure 16. Binding Configuration tab

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 25 of 35

developerWorks

ibm.com/developerWorks

Under the Request Receiver Binding Configuration Details there are three important pieces of information used for verifying signed data: Signing Information Trust Anchor Certificate Store List Select Signing info and click on Edit. Looking at this, you can see how the server treats incoming messages. Any message that comes in includes the names of its canonicalization, digest, and signature algorithms. The server uses these, along with the public key included in the message, to confirm that the message has not been tampered with. Then it needs to confirm that the public key itself is genuine. The server has a list of different Signing info instructions, one for each combination of different algorithms. It finds the appropriate Signing info which gives it a Certificate Store List and a Trust Anchor keystore location. Typically, a public key is certified by an intermediate certificate (or chain of certificates), which are listed in the Certificate Store List. The highest certificate in this chain is then certified by a trusted root certificate which is in the servers Trust Anchor keystore. Hence it can trust the public key. This example carries on to invoke the Web service with your Java client and its sample digital signature certificate and use a .NET client with a different certificate.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 26 of 35

ibm.com/developerWorks

developerWorks

You are going to use the same three algorithms as the sample uses, since they are the standard choices. Since you can only have one set of certificates and trust anchor for each combination of algorithms, all you need to do is put your root CA certificate in the same Trust Anchor keystore. The easiest way to do this is to use the Java keytool (you may wish to back up the keystore first): keytool -import -keystore {location of dsig-receiver.ks} -file {wherever you saved interops-root.cer} Keystore password: server (listed in the Trust Anchor information). If you have selected the default installation directory for Application Developer, the location of dsig-receiver.ks is C:\Program Files\IBM\WebSphere Studio\Application Developer\v5.1\runtimes\base_v5\etc\ws-security\samples. You now have the appropriate certificate settings, but there is one more thing you need to change. The default setting for Application Developer is to act as an intermediary between Web services and their clients. In order that the .NET client can access the Web service directly, do the following: 1. 2. 3. 4. Select the Security Extensions tab of webservices.xml and expand Server Service Configuration. Set the Actor URI to be empty. Press <CTRL> + S to save the file. (Optional) If you want your Java client to work with the new setting, expand its WebContent --> WEB-INF directory and open its webservicesclient.xml file. On the Security Extensions tab, the Client Service Configuration Details Actor URI attribute should already be empty. But you will need to change the Request Sender Configuration --> Details Actor attribute to be empty. Save the file. Right click on the server and select Restart Project --> DefaultEAR so that the server picks up the change(s).

5.

Section 6. Digital signature: .NET client

Setting up the references and form
Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved. Trademarks Page 27 of 35

developerWorks

ibm.com/developerWorks

To create your digital signature .NET client, you need a similar form to your first client. 1. 2. 3. 4. 5. Start Visual Studio .NET. Create a new Visual Basic .NET project. Select the Windows Application type and call it SecureInteropsDsig. Delete the blank form and copy across the form that you used in the last client. Add the Microsoft.Web.Services.dll reference to the project. Add a Web reference to the new bookstoreDsig Web service. Assuming your Web service is running on the same machine, the location of the WSDL file will be http://localhost:9080/bookstoreDsig/wsdl/com/ onlinebookstore/www/bookstore.wsdl. Set the name of the reference to be bookstoreDsig. Change the OrderBookService class so that rather than inheriting from System.Web.Services. Protocols.SoapHttpClientProtocol it inherits from Microsoft.Web.Services. WebServicesClientProtocol. Again, you want to look at the client messages using the TCP monitor, so change the port number in the address from 9080 to 9081. Then close the OrderBookService code window.

6.

7.

Writing the code

Right click on the form and select View Code from the menu. Add a third import statement above the class definition:
Imports Microsoft.Web.Services.Security.X509

In the code for invoking the Web service you need to do four things: 1. 2. 3. Read the security certificate from the Windows keystore Add the public key from the certificate to the message Add the digital signature to the message

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 28 of 35

ibm.com/developerWorks

developerWorks

4.

Invoke the Web service.

As before, you also need to set the mustUnderstand path header attribute to false. Replace the contents of the InvokeWebService Click method with the following code:
Dim WebService As New bookstoreDsig.OrderBookService Dim privateKeyCertificate As X509Certificate Dim store As X509CertificateStore store = X509CertificateStore.CurrentUserStore(X509CertificateStore.MyStore) store.OpenRead() For Each certificate As X509Certificate In store.Certificates If (certificate.GetName.IndexOf("InteropsDsig") > -1) Then privateKeyCertificate = certificate End If Next certificate WebService.RequestSoapContext.Path.MustUnderstand = False Dim digitalSignatureSecurityToken As X509SecurityToken = New X509SecurityToken(privateKeyCertificate) WebService.RequestSoapContext.Security. Tokens.Add(digitalSignatureSecurityToken) Dim digitalSignature As New Signature(digitalSignatureSecurityToken) digitalSignature.SignatureOptions = SignatureOptions.IncludeNone digitalSignature.SignatureOptions = SignatureOptions.IncludeSoapBody WebService.RequestSoapContext.Security.Elements.Add(digitalSignature) WebService.orderBook(Input.Text)

The ClearTextBox code should be correct, so you can leave it as it is.

Running the .NET client

To run the .NET client from within Visual Studio, select the project, right click and select Debug --> Start New Instance. Type in a book title and click Invoke Web Service. You have now invoked a Java Web service from a .NET client using a digitally-signed message. The SOAP message should look like this (edited to be readable):
<?xml version="1.0" encoding="utf-8"?> <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"> <soap:Header> <wsrp:path soap:actor="http://schemas.xmlsoap.org/soap/actor/next" xmlns:wsrp="http://schemas.xmlsoap.org/rp"> <wsrp:action></wsrp:action>

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 29 of 35

developerWorks

ibm.com/developerWorks

<wsrp:to> http://localhost:9081/bookstoreDsig/services/OrderBook </wsrp:to> <wsrp:id> uuid:941947d1-42ed-4506-a03e-b51760085f7c </wsrp:id> </wsrp:path> <wsu:Timestamp xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> <wsu:Created>2003-12-10T14:19:24Z</wsu:Created> <wsu:Expires>2003-12-10T14:24:24Z</wsu:Expires> </wsu:Timestamp> <wsse:Security soap:mustUnderstand="1" xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/07/secext"> <wsse:BinarySecurityToken ValueType="wsse:X509v3" EncodingType="wsse:Base64Binary" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility" wsu:Id="SecurityToken-bd7524e0-271b-4aad-ad21-deccc3c0412f"> MIICvDCCAiWgAwIBAgICEAIwDQYJKoZIhvcNAQEEBQAwgY0xCzAJBgNVBAYTAkdCMRIw EAYDVQQIEwlIYW1wc2hpcmUxEDAOBgNVBAcTB0h1cnNsZXkxDDAKBgNVBAoTA0lCTTEM MAoGA1UECxMDSlRDMRkwFwYDVQQDExBJbnRlcm9wcyBSb290IENBMSEwHwYJKoZIhvcN AQkBFhJwcm9jdG9yQHVrLmlibS5jb20wHhcNMDMxMTI1MTkxMDAyWhcNMDQxMTI0MTkx MDAyWjBIMSMwIQYDVQQDExpJbnRlcm9wcyBkaWdpdGFsIHNpZ25hdHVyZTEhMB8GCSqG SIb3DQEJARYScHJvY3RvckB1ay5pYm0uY29tMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCB iQKBgQC7Bx2ZwpgiHhTKgMfJCwgfTsBpUtWzzxezHaYWsItFb9o90OcpztCphpnTx7q9 JGyPOX5YEuC3Y6KEVlWOqtnZWj7rJhdC54PCWN9GkkxocIY7kFZcVDwjyiji10DoiaEA AJFBwmx8zUdKkzjr9Xz8aBKnTltjSQ1uM3E3YfGXTQIDAQABo28wbTAdBgNVHREEFjAU gRJwcm9jdG9yQHVrLmlibS5jb20wDAYDVR0TAQH/BAIwADAfBgNVHSMEGDAWgBRqZ+vp OtLku+NijlLGI3VvglJfjDAdBgNVHSUEFjAUBggrBgEFBQcDAgYIKwYBBQUHAwQwDQYJ KoZIhvcNAQEEBQADgYEAbFyp59aZfAxrdst8rZWSk600gzKj1B8Kxsxf1wE8G7mTE0mZ n+F8axo4vD0wu/vSJHXF15d4D3c6sp4JqDmcqAwpwdqSrS08g+eQ/3ojODNzwBYubUwT Kgsd698FwwoRNBaa8GQ0Q3PTTuTerVQ5eJsHArI8225aryg5MG2v6x4= </wsse:BinarySecurityToken> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> <SignedInfo> <CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> <SignatureMethod Algorithm="http://www.w3.org/2000/09/xmldsig#rsa-sha1" /> <Reference URI="#Id-f687f36f-ad2e-4aff-87b4-321894fcdcff"> <Transforms> <Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" /> </Transforms> <DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" /> <DigestValue>zHCJj7igcpYBIAOee5i/lNRTbBg=</DigestValue> </Reference> </SignedInfo> <SignatureValue> fNrmCRLAjDK8luUepEIL3u/AD593pW+kr+IVn3LNpTguFH+dKV0QRVfMc5rr+ jGDeO54AJ1PuIdAre4xDTf+CEnOFsMlc4iK/dLAPRbjROBtL6vSGCAfy3sXq/ ralg5qC1epDW4FNN+QVAOa+549qw0AoxgiJSjlQFgeoucG10g= </SignatureValue> <KeyInfo> <wsse:SecurityTokenReference> <wsse:Reference URI="#SecurityToken-bd7524e0-271b-4aad-ad21-deccc3c0412f" /> </wsse:SecurityTokenReference> </KeyInfo> </Signature> </wsse:Security> </soap:Header> <soap:Body wsu:Id="Id-f687f36f-ad2e-4aff-87b4-321894fcdcff" xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"> <bookTitle xmlns="http://www.onlinebookstore.com"> Crime and Punishment</bookTitle> </soap:Body> </soap:Envelope>

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 30 of 35

ibm.com/developerWorks

developerWorks

Using XML Digital Signature as a means of authentication

There are a number of tasks you need to carry out if you wish to configure the example to use digital signature as a means of authentication. See the section for links to documents which will go through these steps in more detail. Server: use the webservices.xml file's Security Extensions and Binding Configuration tabs to select signature as the authentication method. Server registry: signature is not currently supported for Web clients using a local OS user registry, so you will need to configure either a LDAP or custom registry. Java client: use the webservices.xml file's Security Extensions and Port Binding tabs to select signature as the authentication method. .NET client: no changes required, although you may wish to add code to deal with the situation in which authentication is not successful.

Section 7. Summary
Wrap-up
You have learned that basic authentication is the process of sending a username and password in a SOAP message in order to identify the sender of the message. You created a Java Web service and used the webservices.xml file to configure it for basic authentication, using the local registry of your computer as your list of users. You then created a .NET client for it in which you added a username token to the SOAP message. This token contained an appropriate username and password and allowed the Java Web service to understand your message. To improve upon the security that basic authentication offers, you moved on to digital signature. You have seen that by using a wizard, you can create a Java Web service that uses digital signature and have explored how to use the webservices.xml security extensions and binding configuration sections. By altering these settings, you configured the Web service it to use your own Java keystore. You then learned how to create a .NET client which used a PKCS12 certificate to create an X509SecurityToken and Signature for the SOAP message it used to invoke your Java Web service.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 31 of 35

developerWorks

ibm.com/developerWorks

Interoperability can only be as good as the standards that have been defined for it. The WS-Security specification is currently the most important document in this area, but new standards are constantly being proposed. If you try to construct interoperable Web services in an area where standards are loosely defined, you may find that different vendors' implementations vary. Most of what we have covered is well defined, but you should also remember that the default settings of Application Developer and .NET are different. while these settings can be changed, if you forget to, you could have problems. The key points to remember are: Whether you wish to use an intermediary (Actor URI). What digital signature algorithms your client uses. Whether you wish to process the path header. Whether you want to use a timestamp. If you are having problems with an interoperability trial, make sure you use a tool such as the TCP/IP Monitor to visually inspect the SOAP messages. The XML tags may show you that there is a difference in the way two vendors have implemented a standard. Also, be very careful with your security certificates. Since Java keystores are a different certificate format to PKCS, you need to ensure that the certificate the client uses correctly corresponds to the one the server uses and that no errors have been introduced by converting the certificate from one format to another.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 32 of 35

ibm.com/developerWorks

developerWorks

Downloads
Description
source files Information about download methods

Name
ws-secintcode.zip

Size
5KB

Download method
HTTP

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 33 of 35

developerWorks

ibm.com/developerWorks

Resources
Learn WebSphere Application Server Web Services Security documentation -includes a good explanation of both authentication and digital signature. For more information on WS-Security using Microsoft .NET, try WS-Security Authentication and Digital Signatures with Web Services Enhancements. It covers basic authentication using a username and password, an X.509 certificate, or digital signature. WS-Security Specifications 1.0 -- the formal specification for Web services authentication, digital signature and encryption, written by IBM, Microsoft and Verisign. The Web Services Interoperabilty Organization (WS-I.org) addresses many issues of interoperability between different implementations of Web services through Profiles of how specifications like WS-Security should be implemented. WebSphere Application Server InfoCenter -- explains the difference between WebSphere Application Server security and Java 2 security and also what types of user registries can be used for authentication. X.509 Certificates and Certificate Revocation Lists -- a document from Sun which explains what X.509 certificates are and which Java APIs and tools relate to them. Java Keytool Documentation -- explains how to use the Java Keytool to generate self-signed certificates or import and export certificates from JKS or JCEKS keystores. Introduction to the PKCS Standards -- an overview of the widely used PKCS cryptography standards, written by an employee of RSA, the company that developed PKCS. How Digital Signatures Work: Digitally Signing Messages -- a good explanation of how digital signatures work. SOA and Web services -- hosts hundreds of informative articles and introductory, intermediate, and advanced tutorials on how to develop Web services applications. Get products and technologies openssl.org -- the OpenSSL Project is an open source initiative that supplies a toolkit that implements Secure Socket Layer (SSL) and Transport Layer Security (TLS) as well as providing a cryptography library. The toolkit can be used to generate self-signed certificates in a multitude of formats.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 34 of 35

ibm.com/developerWorks

developerWorks

Discuss developerWorks blogs -- get involved in the developerWorks community.

About the author

Hedley Proctor Hedley Proctor is a software engineer at IBM Hursley, England. He has worked on versions 5 and 5.1 of the WebSphere SDK for Web Services, specializing in the Eclipse plugins, samples and interoperability. He took an undergraduate degree in Physics at Oxford University and a Postgraduate Diploma in Philosophy at Durham University, before joining IBM in September 2002.

Secure Web services: Interoperability Copyright IBM Corporation 2004. All rights reserved.

Trademarks Page 35 of 35