Confidentiality and integrity are two critical components of web services. While confidentiality can be ensured by means of encryption, the encrypted data can still be overwritten and the integrity of the message can be compromised. So it becomes is equally important to protect the integrity of the message; digital signatures helps us in doing just that.
Overview of Digital Signatures
In the web services scenario, XML messages are exchanged between the client application and the web services. Certain messages contain critical business information, and therefore the integrity of the message should be ensured. Ensuring the integrity of the message is not a new concept, it has been there for a long time. The concept is to make sure that the data was not tampered while in transit between the sender and the receiver.
Consider, for example, that Alice and Bob are exchanging emails that are critical to business. Alice wants to make sure that Bob receives the correct email that she sent and no one else tampered with or modified the email in between. In order to ensure the integrity of the message, Alice digitally signs the message using her private key, and when Bob receives the message, he will check to make sure that the signature is still valid before he can trust or read the email.
What is this digital signature? And how does it prove that no one else tampered with the data? When a message is digitally signed, it basically follows these steps:
- Create a digest value of the message(a unique string value for the message using a SHA1 or MD5 algorithm).
- Encrypt the digest value using the private key—known only to the sender.
- Exchange the message along with the encrypted digest value.
MD5 and SHA1 are message digest algorithms to calculate the digest value. The digest or hash value is nothing but a non-reversible unique string for any given data, i.e. the digest value will change even if a space is added or removed. SHA1 produces a 160 bit digest value, while MD5 produces a 128 bit value.
When Bob receives the message, his first task is to validate the signature. Validation of signature goes through a sequence of steps:
- Create a digest value of the message again using the same algorithm.
- Encrypt the digest value using the public key of Alice(obtained out of band or part of message, etc.)
- Validate to make sure that the digest value encrypted using the public key matches the one that was sent by Alice.
- Since the public key is known or exchanged along with the message, Bob can check the validity of the certificate itself.
Digital certificates are issued by a trusted party such as Verisign. When a certificate is compromised, you can cancel the certificate, which will invalidate the public key.
Once the signature is verified, Bob can trust that the message was not tampered with by anyone else. He can also validate the certificate to make sure that it is not expired or revoked, and also to ensure that no one actually tampered with the private key of Alice.
Digital Signatures in Web Services
In the last section, we learnt about digital signatures. Since web services are all about interoperability, digital-signature-related information is represented in an industry standard format called XML Signature (standardized by W3C). The following are the key data elements that are represented in an interoperable manner by XML Signature:
- What data (what part of SOAP message) is digitally signed?
- What hash algorithm (MD5 or SHA1) is used to create the digest value?
- What signature algorithm is used?
- Information about the certificate or key.
In the next section, we will describe how the Oracle Web Services Manager can help generate and verify signatures in web services.
Signature Generation Using Oracle WSM
Oracle Web Services Manager can centrally manage the security policy, including digital signature generation. One of the greatest advantages in using Oracle WSM to digitally sign messages is that the policy information and the digital certificate information are centrally stored and managed.
An organization can have many web services, and some of them might exchange certain business critical information and require that the messages be digitally signed. Oracle WSM will play a key role when different web services have different requirements to sign the message, or when it is required to take certain actions before or after signing the message. Oracle WSM can be used to configure the signature at each web service level and that reduces the burden of deploying certificates across multiple systems. In this section, we will discuss more about how to digitally sign the response message of the web service using Oracle WSM.
Sign Message Policy Step
As a quick refresher, in Oracle WSM, each web service is registered within a gateway or an agent and a policy is attached to each web service. The policy steps are divided mainly into request pipeline template and response pipeline template, where different policies can be applied for request or response message processing. In this section, I will describe how to configure the policy for a response pipeline template to digitally sign the response message.
It is assumed that the web service is registered within a gateway and a detailed example will be described later in this article .
In the response pipeline, we can add a policy step called Sign Message to digitally sign the message. In order to digitally sign a message, the key components that are required are:
- Private key store
- Private key password
- The part of SOAP message that is being signed
- The signature algorithm being used
The following screenshot describes the Sign Message policy step with certain values populated.
In the previous screenshot, the values that are populated are:
- Keystore location—The location where the private key file is located.
- Keystore type—Whether or not it is PKCS12 or JKS.
- Keystore password—The password to the keystore.
- Signer's private-key alias—The alias to gain access to the private key from the keystore.
- Signer's private-key password—The password to access the private key.
- Signed Content—Whether the BODY or envelope of the SOAP message should be signed.
The above information is a part of a policy that is attached to the time service which will sign the response message. As per the information that is shown in the screenshot, the BODY of the SOAP message response will be digitally signed us in the SHA1 as the digest algorithm, and PKCS12 key store. Once the message is signed, the SOAP message will look like:
<?xml version="1.0" encoding="UTF-8"?>
instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:
<soap:Body wsu:Id="ishUwYWW2AAthrxhlpv1CA22" xmlns:wsu="http://
<Result xsi:type="xsd:string">10:13 AM</Result>
Internals of Sign Message Policy Step
The example XML message is nothing but the SOAP response message that is digitally signed by Oracle WSM. The parameters that are selected or that can be selected will affect the message output and hence it is important to understand how Oracle WSM assembles the digitally signed message.
First of all, Oracle WSM was configured to sign the SOAP body message, which in our example is the actual time from the server. In the above example, the SOAP body is referenced by the identifierishUwYWW2AAthrxhlpv1CA22. Only the SOAP body message should be digitally signed. We understand that in the signature generation process, we should first calculate the digest value of the message and then encrypt the digest value. In the sample XML, there are a few components which are worth explaining.
The Reference element describes what part of the message is hashed and what digest algorithm is used to create the hash value and any transformations applied before the digest was calculated.
Let's consider a portion of our signed response message and in the message below, we will notice that the DigestMethod is SHA1 and, that the DigestValue is also embedded.
In the above example, there is also an element called Transforms which contains a list of transform elements. The Transform element describes what transformation is applied to the XML message before the digest is calculated. In our example, the Exclusive Canonicalization transformation is used.
Since the digest values can differ even when a space is added or removed, canonicalization transformation will transform the data to an accepted format before the digest is calculated.
The SignedInfo element describes the actual signature algorithm and a list of references that contain the digest value of the message. In our case, the signature algorithm is rsa-sha1 and it also contains a reference to the SOAP Body element (Id attribute of the SOAP Body element). In our example of signed SOAP response message, there are actually two reference elements: one that refers to the SOAP Body and an other that refers to the Timestamp element. The SignatureMethod element describes the actual signature algorithm used.
The Signature element is the root element that describes the digital signature. It contains theSignedInfo element, SignatureValue and the KeyInfo element. The SignatureValue element contains the actual signature value and the KeyInfoelement contains information about the certifcate.
Signature Generation and Verification Example
In an earlier section, we learnt how the sign message policy step can be configured to digitally sign the message and also the internals of how Oracle WSM creates the signed SOAP response message. In the following article, we will walk through the signature generation and verification process within Oracle WSM by means of an example. In this example, we will have the same time web service which will be registered within Oracle WSM Gateway. Oracle WSM will validate the incoming signed SOAP message and then will respond with a signed SOAP message. In this example we will demonstrate how:
- To register web service with Oracle WSM
- Oracle WSM can be configured to validate the signature in SOAP request
- A Microsoft .NET application can digitally sign the SOAP request
- Oracle WSM can be configured to sign the response SOAP message
- A Microsoft .NET application can validate the signature of the SOAP message
Of the above listed, the first point will be covered in this article and the remaining will be explained the following part of this article.
Registering Web Service with Oracle WSM
In order to protect a web service within Oracle WSM, the first step is to register the web service within Oracle WSM and then edit the policy associated with it. The following steps describe how to register the service:
Login to Oracle Web Service Manager Console at:
Click on Policy Management and then Manage Services; you will see the List of Gateways that are available as shown in the following screenshot.
On the right side of the screen, if you click on the Services hyperlink, you will see the list of registered services (refer to the following screenshot).
In order to add a new service, click on Add New Service on the right side panel.
The previous screenshot show the details that can be added while adding the new service. The * after each label makes those fields mandatory. The screen asks for typical information such as:
- Name of the service
- Version of the service
- Any description of the service
- WSDL URL of the service
- Protocol in which service will accept messages
It also asks for additional information such as Service Groups, groups that are part of Oracle WSM with the right to view and with the right to update.
In our example, we are registering time service that will validate the signature of the web service request and then will sign the response message. The time service is registered with the following information:
- Service Name: Verify And Sign
- Service Version: 1
- Service Description: Verify Incoming message and Sign Outgoing message
- WSDL URL: http://owsm.packtpub.com:3115/ccore/TimeService.wsdl
- Service Protocol: HTTP(S)
- Service Groups: Select the default that has full permissions
Once the information is filled out, click Next on New Service registration. This will take you to the next screen which will display the actual URL of the service (refer to the following screenshot).
The URL in this page comes from the WSDL URL. You just have to make sure that the service is enabled and check if it is SOAP service or not.
You can then click Finish to register the service. Once you click Finish, the Oracle WSM internally generates a new service ID and now the client applications can use that service ID to communicate.
The previous screenshot show that the Oracle WSM registered the time service and created a new service ID.
Click OK to get back to the main screen that lists all the services.
We have only added the new service, but it hasn't been committed yet. You can now click OK to commit the policy.
Don't miss out on the other interesting aspects of this topic!! Go head and check out —Digitally Signing and Verifying Messages in Web Services- part 2 — to get further in depth understanding of the topic.
If you have read this article you may be interested to view :
- Oracle Web Services Manager: Authentication and Authorization
- Digitally Signing and Verifying Messages in Web Services- part 2