News Stay informed about the latest enterprise technology news and product updates.

Implementing WS-Security

This article describes how the emerging WS-Security standard was used to secure a Web service that was developed and deployed in the fall of 2002. The article will discuss the security-related requirements of the Web service and how they were met using a combination of HTTPS/SSL, digital certificates, and digital signature technologies. The article will crawl through the WS-Security element of the SOAP message used to trigger the Web service, explaining each section of the WS-Security element in detail. After reading this article, you should have a better understanding about how you can use WS-Security in a production Web service application and feel confident about using this emerging standard in your own projects.

First published on IBM developerWorks.

Case Study

Implementing WS-Security
Sam Thompson
jStart Program Manager for Web services, IBM
1 April 2003

This article describes how the emerging WS-Security standard was used to secure a Web service that was developed and deployed in the fall of 2002. The article will discuss the security-related requirements of the Web service and how they were met using a combination of HTTPS/SSL, digital certificates, and digital signature technologies. The article will crawl through the WS-Security element of the SOAP message used to trigger the Web service, explaining each section of the WS-Security element in detail. After reading this article, you should have a better understanding about how you can use WS-Security in a production Web service application and feel confident about using this emerging standard in your own projects.

Web services security - ready to do business
Over the past couple of years, Web services has gone from being an overly-hyped technology to one that many organizations are using productively. The early implementations, like all new technology projects, tended to be sandbox-type efforts or projects that were small, inside the firewall, and non-mission-critical in nature. Those brave souls that tried to venture into the world of delivering Web services over the Internet found that they either had to provide services that were open and available for use by anyone (for example XMethods or Amazon) or had to develop their own, typically proprietary, very company-specific, security scheme.

Early adopters using the Internet as their transport typically used some form of registration process (for example Google) for open Internet services or only provided services to a small number of business partners with whom they already had a tight, trusted relationship. For example, in order to use Google's Web service-enabled search engine, the service requester must first register with Google through an HTML based form. As part of the registration process, Google sends the requester an email with a security "token". When the requester invokes the service, they provide this token to Google as part of the SOAP message to verify that they are a registered, authorized user of the Google Web service.

In these situations, even though service providers were using industry standards such as SOAP, additional information concerning the security scheme/process needed to be provided in order for the service requestors to be able to use the service. This had a rather undesired effect of tightly coupling the requester and the provider, a scenario that wasn't desired by either party.

The WS-Security Standard
Clearly an industry standard way of securing a Web service was required, and IBM, Microsoft, and VeriSign responded to this need in April, 2002. From the WS-Security specification (see also Resources):

"WS-Security describes enhancements to SOAP messaging to provide quality of protection through message integrity, message confidentiality, and single message authentication. These mechanisms can be used to accommodate a wide variety of security models and encryption technologies.

WS-Security also provides a general-purpose mechanism for associating security tokens with messages. No specific type of security token is required by WS-Security. It is designed to be extensible (e.g. support multiple security token formats). For example, a client might provide proof of identity and proof that they have a particular business certification."

Since 1997, IBM has had a program called jStart (short for jump-start -- see Resources) to help its customers and business partners work with new emerging technologies. The program's goal is to help early adopters leverage new technologies to help make their businesses more successful. Last fall, the jStart program worked with a company who wanted to provide a business-to-business Web service using the Internet as a transport. They desired a strong level of security and interoperability, and they decided to use a WS-Security approach to secure the SOAP message traffic with their business partners. This paper discusses that project and its use of WS-Security.

Why WS-Security?
As the use cases for our customer's application were being developed, a set of security-related, non-functional requirements were identified:

  1. The communication between our customer and his business partner should not be able to be viewed by a third party as it travels on the Internet.
  2. Our customer needed to be able to determine from whom the message was coming and be able to verify that the sender was who the sender claimed to be.
  3. Our customer needed to be able to ensure that the data being transmitted was not tampered with.

Non-functional requirement #1 will be addressed through the use of HTTPS/SSL transport security. Since this application will be a point-to-point application, with no third party service providers or intermediaries involved, the idea of using cryptography to encrypt all or part of the SOAP message was evaluated but not implemented at this time. Given no third parties were involved, the value gained from an additional encryption step that would encrypt a segment of the SOAP message was not enough to justify the additional development expense and complexity that would have been needed to implement a form of message-level encryption.

Non-functional requirements #2 and #3 will be addressed through the use of digital signatures and digital certificates. When using a digital certificate approach, the Web service requester must have a digital certificate which has been signed by a trusted certificate authority. The requester will use this certificate to assert their identity and will digitally sign the SOAP message so that the requester's identity and the message's integrity can be verified.

Once the message is received at our customer's system, it will be time stamped and logged. At this point, the digital signature will be validated. The validation process will ensure that the message came from the sender as well as verify that the message contents have not been modified since it was signed at the sender's site. The SOAP message log that our customer creates in DB2 will be used for non-repudiation purposes.

The Web service
Now that you understand the requirements and the technical approach, let's take a look at what was implemented. The application that our customer chose to implement as a Web service was developed using WebSphere Studio Application Developer and some tools from the IBM alphaWorks Web site, namely, the XML Security Suite, and the Apache Axis run time that was part of the IBM Web Services Toolkit. Although the application is quite powerful as it drives our customer's core business application, it is simple in that it only implements one method. It was deployed on WebSphere Application Server and interacts with the customer's core business application through WebSphere MQ Series.

By using the TCP/IP monitor that is part of Application Developer, we've captured the SOAP message that is sent to the Web service for processing. Note that in order to maintain the confidentiality of our customer, we made the SOAP URLs generic, removed the application-specific SOAP payload, and slightly modified some of the calculated values:

1.  <soapenv:Envelope xmlns:soapenv="" 

2.  <soapenv:Header>

3.  <wsse:Security soapenv:actor="" 
        <Signature xmlns="">

4.  <SignedInfo>

5.  <CanonicalizationMethod Algorithm=""/>

6.  <SignatureMethod Algorithm=""/>

7.  <Reference URI="#sign_content_1043176028580">

8.  <Transforms>

9.  <Transform Algorithm=""/>

10.  </Transforms>

11.  <DigestMethod Algorithm=""/>

12.  <DigestValue>FLuQTa/LqDIZ5F2JSaMRHSRuaiQ=</DigestValue>

13.  </Reference>

14.  </SignedInfo>

15.  <SignatureValue>

16.  kGlrrXjKku/WXKxID+JJkEXY+aGNYHc5dy8GwbLFtB5Msll2/MhwdnO9wastJ0gLPzLy3oHL

17.  7A8ggkMkjgAqnLg6PTzM7MdKoIAhe+xRHdOysamGucFJQRMrU+JQ4WATJt0bpdClwJy6mexT

18.  Su48mq1q5rM9YZh61P7UEUKt+EQ=

19.  </SignatureValue>

20.  <KeyInfo xmlns="">

21.  <KeyValue>

22.  <RSAKeyValue>

23.  <Modulus>

24.  2sW+eBjx5D2QMyr8ocZIZWNYHGf9zYhB4XWILPCTvhNV7dIe3l8ARepOA1ABFK2OMy

25.  pzb+Rb+nWQeo//yFz/28PmL63kdLiE72qmmQuzuPa5NXaV9pJ4JKw86QdLhGGpFIRH

26.  18Iugf3xLFwQEZqKYnblTUs7ftnTgW5r4HH492k=

27.  </Modulus>

28.  <Exponent>AQAB</Exponent>

29.  </RSAKeyValue>

30.  </KeyValue>

31.  <X509Data>

32.  <X509IssuerSerial>

33.  <X509IssuerName>OU=Java,O=IBM,L=Unknown,ST=Oklahoma,C=US</X509IssuerName>

34.  <X509SerialNumber>0</X509SerialNumber></X509IssuerSerial>

35.  <X509SubjectName>CN=John Doe</X509SubjectName>

36.  <X509Certificate>





41.  RepOA1ABFK2OMypzb+Rb+nWQeo//yFz/28PmL63kdLiE72qmmQuzuPa5NXaV9pJ4JKw86QdLhGGp

42.  FIRH18Iugf3xLFwQEZqKYnblTUs7ftnTgW5r4HH492kCAwEAATANBgkqhkiG9w0BAQQFAAOBgQCs

43.  OD02WMoYcMR7Sqdb9oQyk7Nn4rQ5DBgZ5mxGGVzWxBZW/QON+Ir2j4KUjX1jalMvbHa9lnhPQmJi

44.  Ued923rza7fvdRG2CDalbW0R3aPd5q0u3akP0/Ejb7z5o88heajCSgfRruvU+ZdOTT3Oe+RBQgw8

45.  VuzbLApPnXiehowYuA==

46.  </X509Certificate>

47.  </X509Data>

48.  </KeyInfo>

49.  </Signature> 

50.  </wsse:Security>

51.  </soapenv:Header>

52.  <soapenv:Body>

53.  application specific data/content

54.  </soapenv:Body>

55.  </soapenv:Envelope>:

Let's look at the SOAP message in greater detail. As you can plainly see, this is a typical SOAP message with an outermost opening and closing <soapenv:Envelope> tag set. The SOAP envelope contains <soapenv:Header> and <soapenv:Body> sections. The WS-Security section, as defined by the WS-Security specification, is positioned within the SOAP Header and is designated by the opening and closing <wsse:Security> block, lines 3-51. The <Security> header block provides a mechanism for attaching security-related information targeted at a specific receiver (the SOAP actor). Since only one SOAP actor is involved in this use case, only one <Security> header block is contained in the message.

In line 3, the SOAP actor attribute defines the recipient of a header entry, Security soapenv:actor="". Line 3 also contains the soapenv:mustUnderstand="1" attribute. By setting the SOAP mustUnderstand attribute to "1", we indicate that the service provider must process the SOAP header entry. As per the SOAP specification, since the attribute is set to "1", if the receiver cannot obey the semantics (as conveyed by the fully qualified name of the element) and process the message according to those semantics, the receiver MUST fail processing the message and generate a fault.

SignedInfo and Digests
Lines 4-14, <SignedInfo> </SignedInfo>, describes the signed content of the message. Note that as is customary with digital signature applications, a digest is used to facilitate faster processing. This is a standard industry practice and is done for performance reasons. The payload (the SOAP Body) of our SOAP message is quite long, and the process of applying a public key algorithm to the full message could significantly impact the performance of our Web service. As such, a digest is used. A digest is a fixed length, short message whose digital signature can be quickly generated and verified. When the message is received, our Web service digital signature verifier class (implemented as an Apache Axis plugable provider) will compute the digest and verify that the newly-computed digest matches the digest that was sent.

Let's look at the elements that make up the Signed Content portion of the message. Line 5, <CanonicalizationMethod Algorithm=""/>, identifies the canonicalization algorithm that is used to create a canonicalized form of the information being signed -- in this case, the digest. This step is needed because of the nature of XML documents and the programming tools that work with them. XML documents, in some cases, can have slight textual differences, yet be essentially the same logical document. Small variations in the way comments are represented or in the way an XML parser handles line delimiters when serializing/deserializing an XML data structure can create slightly different binary representations of the same content. If the algorithm that verifies the digital signature were to be run against a slightly different serialized version of the data, the result could be a fail when indeed it should be a pass.

To avoid this problem, the document is first transformed into its canonicalized form through the use of a canonicalization algorithm. This algorithm, an implementation of the W3C Exclusive XML Canonicalization Version 1.0 Specification (see Resources), a W3C recommendation, transforms the document into its basic canonicalized form. This allows us to get a consistent binary representation that can be correctly compared and thus yield the correct result.

Line 6, <SignatureMethod Algorithm=""/>, indicates the Signature Method Algorithm. This is the algorithm that is used to convert the output of the canonicalization algorithm into the Signature Value. Our signature algorithm is a combination of a key dependent algorithm (RSA) and a hash algorithm (SHA1). This algorithm is an implementation of the RSASSA-PKCS1-v1_5 specification described in W3C RFC 2437 (see Resources).

Line 7, <Reference URI="#sign_content_1043176028580">, indicates the reference element. The optional URI attribute of Reference identifies the data object that was signed. The Reference block includes the algorithm that is used to compute the digest, the digest value that was computed, and the final transform that is performed prior to computing the digest value. Lines 8-10, <Transforms> <Transform Algorithm=""/> </Transforms>, indicate the transformation algorithm, while lines 11 and 12 specify the digest algorithm and the computed digest value, <DigestMethod Algorithm=""/> <DigestValue>FLuQTa/LqDIZ5F2JSaMRHSRuaiQ=</DigestValue>.

In our application, the Transform algorithm is once again the W3C Exclusive XML Canonicalization algorithm discussed above. The method used to compute the digest, the Secure Hash Algorithm, is part of the U.S. Department of Commerce/National Institute of Standards and Technology's Secure Hash standard.

Lines 15-16, <SignatureValue>kGlrrXjKku/WXKxID+JJkEXY+aGNYHc5dy8GwbLFtB5Msll2/MhwdnO9wastJ0gLPzLy3oHL
, contain the signature value, which is actually the encrypted digest value. This value is the output of the Signature Method Algorithm indicated on line 6.

Lines 20-48 introduce the concept of keys. A key is used to mathematically transform a normal, readable text message into an unreadable one for transmission across the internet. Our Web service will use a public/private-key (a pair of mathematically related keys) or an asymmetric key encryption scheme. One of these keys is kept secret; this is the private key. In our application, the Web service requester will sign the digest with his private key prior to sending the document to the service provider.

Line 20 begins the Key Value block and identifies the namespace that we will use -- <KeyInfo xmlns="">. The Key Value block, <KeyValue> <RSAKeyValue> </RSAKeyValue> </KeyValue>, is where the Web service requester supplies the Web service provider with the information they need in order to obtain the key needed to validate the signature. In our message, the KeyValue element contains the requester's public key, which will be used to validate the signature. We have chosen to use an asymmetric RSA (named after the three inventors, Rivest, Shamir, and Adleman) key-based approach in order to meet our non-repudiation requirement.

The use of the RSA key scheme assures our Web service provider that the message was in the same form that it was received, and it was signed by the owner of the extracted digital certificate. If the recomputed digest matches the decrypted digest from the SOAP message, the service provider is able to verify the integrity of the message. By logging the message before any processing is done (the log is implemented as the first Apache Axis handler in the handler chain), the Web service provider can prove that the message in question was sent by whomever signed the message and that it was received unmodified from the form in which is was sent.

RSAKeyValue elements have two fields:





The RSA scheme uses large prime numbers to construct the key pairs. The Modulus is the product of two large prime numbers. Each pair shares the Modulus, but each also has a specific exponent. The RSA Laboratories' Frequently Asked Questions About Today's Cryptography, Version 4.1 document (see Resources) describes how the Modulus and the Exponent are created:

"Take two large primes, p and q, and compute their product n = pq; n is the modulus. Choose a number, e, less than n and relatively prime to (p - 1)(q - 1), which means that e and (p - 1)(q - 1) have no common factors except 1. Find another number d such that (ed - 1) is divisible by (p - 1)(q - 1). The values e and d are called the public and private exponents, respectively. The public key is the pair (n, e); the private key is (n, d)."

The service requester digitally signs the message with their private key. On the service provider side, the signature is verified using the requester's public key. Since the service requester signs the message with a private, asymmetric key, the service provider is assured that the only organization that could have signed the message is the holder of the private key.

Digital Certificates
The next section of the Key Info block is the digital certificate itself as indicated by the <X509Data> element. The digital certificate is used to identify the sender of the message in the way a user ID is used to identify the user of Web and enterprise applications. The first element in this block of data identifies the organization that signed the certificate. This is typically the certificate authority. In our case, that information has been replaced with generic information: <X509IssuerSerial> <X509IssuerName>OU=Java,O=IBM,L=Unknown,ST=Oklahoma,C=US</X509IssuerName> <X509SerialNumber>0</X509SerialNumber></X509IssuerSerial>

Next is the <X509SubjectName>CN=John Doe</X509SubjectName> element, which contains the distinguished name of the service requester -- in our case, simply John Doe -- and finally the X.509 certificate itself:


The final stage of WS-Security processing is to validate the Web service requester's digital certificate. When using a digital certificate approach, each Web service requester must have a digital certificate which a trusted Certificate Authority (CA) has signed. The definition of a trusted certificate authority is outside the scope of this paper, but typically either an industry-accepted, 3rd-party certificate authority (a company like VeriSign) performs this role, or the Web service provider takes on the role of the certificate authority for the certificates that their application uses. If the latter approach is used, use of the open source OpenSSL toolkit from Apache, or the basic digital certificate support provided by WebSphere Application Server's IKEYMAN utility is recommended.

In the initial rollout of our application, our customer chose to play the role of certificate authority. As such, they created their own, self-signed CA certificate. Prior to any Web service interactions, the Web service requester must provide the Web service provider with a certificate that they will use in the application. Playing the certificate authority role, the Web service provider signs the certificate and returns it to the Web service requester.

As described above, the Web service requester includes the CA-signed digital certificate in the SOAP message. After the digital signature has verified the integrity of the message, the certificate is extracted from the message and validated using the CA's public key. Once the validity of the certificate has been achieved, the Web service requester will have been authenticated and the processing of the WS-Security portion of the message will be complete. The owner has successfully authenticated to the receiver.

Note that if, at a later date, our service provider chooses to relinquish the role of the certificate authority and use an industry-accepted, trusted, 3rd-party certificate authority, the logic of our validation code does not need to change. In this scenario, prior to using the Web service, the Web service requester will need to get a certificate issued by a trusted certificate authority. The service requester will place this 3rd-party certificate in the SOAP message. When the service provider is validating the digital certificate, instead of using their self-signed CA key, the public key of the 3rd-party CA will be used. In this scenario, the service provider has established a trust relationship with the 3rd-party certificate authority, and the CA will be trusted to adequately authenticate users before issuing certificates to them.

WS-Security and WSDL
One of the promises of Web services is to be able to loosely couple the end points and allow the publishing of services in UDDI directories that can be discovered and invoked dynamically at run time. Unfortunately, at this point in the technology life cycle, the use of WS-Security in the SOAP message header prevents us from being able to do this. Today's Java to WSDL emitters are not yet able to handle the creation of WSDL documents that appropriately describe the WS-Security requirements. Plus, even if they could, at this stage, development tools such as WebSphere Studio Application Developer or Visual Studio .Net couldn't generate the proxies that handle the WS-Security aspects of the service.

As such, the developers of Web services in early 2003 will need to make a conscious trade-off here. When WS-Security is used, the service provider needs to either provide stubs/proxies which partners can invoke that handle the WS-Security portion of the message or manually communicate the WS-Security requirement of the Web service to their potential business partners and customers. For the WS-Security-based project described in this paper, proxies that properly sign the message and insert the WS-Security element into the SOAP data stream were created for Java technology, COM, and .Net clients. The next generation of Web services development tools from IBM and others should be able to handle the WS-Security elements of a Web service, but for now, developers need to understand that this is an achievable, but manual process.

This paper described an Internet-based Web services application that was developed and deployed in 2002. It was deployed on a WebSphere Application Server and is available for use by our customer's business partners. It demonstrates the soundness and overall viability of the draft WS-Security specification by offering itself as a proof-point that secure, mission critical, Web services applications are viable with today's development tools and deployment platforms. Yes, in our customer's case, some non-automated, manual steps were required to handle the WS-Security element of our SOAP message, but as support for WS-Security gets folded into the next iteration of the WSDL specification and support is added to the Web services development tools of many vendors, it will only get better.


About the author
Sam Thompson joined IBM in 1980 and held various technical and management positions in VM product development. In 1992, Sam moved to the systems management development lab in Raleigh, North Carolina and helped bring several SystemView products to market. When SystemView merged with Tivoli Systems, Sam traveled the world as a technical evangelist explaining the merger, the new Tivoli strategy and products, and the convergence strategy for the IBM and Tivoli workgroup products. In March 1997 he assumed his present position in IBM's Emerging Technologies jStart (jump start) group and works with organizations to help them build solutions that utilize IBM XML, Java, and Web services technologies. You can reach Sam at thompsam at

Dig Deeper on Topics Archive