Security

As we move from the "Hello World" days of Web services toward development that can truly support the enterprise, there are some advanced functional requirements for Web services, including secure messaging, reliable messaging, and Web service policies. Since interoperability is the "Holy Grail" of XML and Web services, we must maintain this interoperability while supporting such advanced Web service functionalities. We can do this by developing and promoting the widespread industry adoption of so-called "advanced" Web service specifications. While you might envision creating a single monolithic specification that defines all such advanced Web service behaviors, this goal is better accomplished as a set of finely scoped, modular, and orthogonal Web services specifications.

Advanced Web Services Specifications
This modular approach to the development of our next generation of Web services specifications has been advanced, in particular by Microsoft, IBM, and a host of other companies. One benefit of using such an architecture of advanced Web services specifications is that you need only implement the particular specifications that provide the functionality required by your application without having to implement the other specifications. The proposed advanced Web services specifications, to varying degrees, leverage the foundational standards of XML, SOAP, and WSDL as well as the underlying transport protocols of TCP and HTTP. Figure 1 shows how advanced Web services specifications provide a modular platform for the development of interoperable Web services to support the enterprise.

Note that in Figure 1 the WS-Security specification is also leveraged by other security specifications to provide even more specific security functionalities.

Securing Web Services
In most ways, you secure a Web service in the same way that you would secure any other Web-based application. Since I don't have the space here to discuss all aspects of implementing end-to-end Web services security, this discussion will focus on the facilities provided by WS-Security for securing SOAP messages. (For an overall discussion of Web services security, pick up a copy of my book, Understanding Web Services Specifications and the WSE). If you have ever written a secure application for the Web, you probably implemented secure socket layer (SSL) security. The "silver bullet" that has driven e-commerce and the dot-com boom, SSL provides security between two parties in an HTTP-based exchange by encrypting messages sent between the two. While SSL is secure, reasonably efficient, and can be used to secure SOAP messaging, it does have a major limitation in an enterprise Web service topology, namely that SSL limits message exchanges to only two parties. For example, a Web service would have to completely decrypt an SSL-secured SOAP message to read the SOAP message headers to determine what to do with the message, even if it is not the final message recipient. In complex Web service topologies where the service has to make such routing and forwarding decisions, WS-Security provides a much better solution as it enables you to secure the critical contents of the message while leaving the SOAP header unencrypted for more efficient routing.

Introducing the WS-Security Specification
WS-Security, proposed by IBM, Microsoft, and VeriSign, introduces the concept of a security token that is transported in the SOAP message header and can be used to authenticate the sender as well as to secure the message itself. In WS-Security, security tokens can be either plain-text or binary. Binary security tokens, which include X.509-based and Kerberos-based tokens, are encoded as base-64 binary XML for transport in the message header. The benefits of using binary security tokens are that they can be used to both digitally sign and encrypt the message, and they themselves can contain digital signatures made by root authorities. Tokens that contain signatures from security authorities are known as signed security tokens. WS-Security leverages existing XML security elements that are defined in other XML security specifications (namely the XML Signature and XML Encryption standards) and defines how they are used to secure SOAP messages.

Listing 1 shows an example of a request message containing an X.509-based security token (the BinarySecurityToken element), where this token is used to digitally sign the message. (For readability, I truncated the token's base-64 encoded data.) Information about how the message was digitally signed, including the data that was signed, the token used for signing, and the signature itself, are included in a Signature element, an XML security element defined in the XML Signature specification. Also, in this listing the body of the message is encrypted using the recipient's public key and included in the message body within the EncryptedData element, an XML security element defined in the XML Encryption specification. Upon receipt, the recipient verifies the signature using the sender's public key in the attached token and decrypts the message body using its private key.

Microsoft Web Services Enhancements
While you could follow the WS-Security specification to write a secure implementation for your Web service, you can avoid this extra work by leveraging Microsoft's implementation provided in their Web Services Enhancements (WSE) product offering. In the rest of this article, I will focus on WSE (I used the 2.0 Beta release for the code shown here) support for WS-Security and show how to use WSE to secure requests to a .NET Web service. While more complete support for advanced Web service standards will be included in the next version of Windows (now code-named Longhorn), WSE can be used today to implement advanced Web services functionalities, including security, reliable messaging, and Web service policies.

WSE is essentially a .NET assembly that supports both TCP and HTTP transports, and implements a set of input and output filters as well as a rich API. The WSE runtime, which hosts these filters and API, is implemented in Microsoft.Web.Services.dll. Input filters read incoming SOAP messages and translate known SOAP header elements into WSE programming objects, which you can access in your code using the SoapContext object, a collection that abstracts the message headers. Figure 2 shows how a SOAP message is passed through the series of input filters, called the input filter "pipeline."

In a similar fashion, WSE output filters construct SOAP headers based on the properties of the SoapContext object for the outgoing message. By properly constructing the SoapContext object, we can secure both request and response messages at both points of a Web service exchange. Later, I will show how to use the SoapContext to secure a Web service request.

Getting Started with WSE
WSE provides full X.509 certificate support for authenticating and securing messages, and this is the type of authentication that I will use in my example. When using X.509 certificates, you first need to obtain and install valid certificates for both the client application and the server hosting the Web service. The server certificate, which must support both encryption and digital signatures, should be installed in the Local Machine store of the server hosting the service. The public key portion of this certificate should also be installed in the Current User store for the computer where any client applications will be run to access the service. These client computers also need to have their own client certificates installed in the Current User store, and these client certificates must also support encryption and digital signatures. Remember, the ASP.NET process that hosts the Web service must be able to access the key file for the X.509 certificates that it needs to use. See the WSE SDK documentation provided with the product for more information on granting WSE the required access to key files.

To help you get started using X.509 certificates, WSE provides you with a set of makecert.exe-generated client and service test certificates. However, for better performance you should obtain your certificates from a certificate authority, even a test one. When you install WSE with the Visual Studio Tools option, you get a handy X.509 Certificate Tool that makes it easier to manage certificates. You also get the WSE Settings Tool, which is a Visual Studio add-in that automatically makes the necessary updates to your application's XML configuration file.

Configuring WSE for Your Project
Since WSE can be employed by both a Web service and the client applications that consume that service, it really makes sense to simplify the discussion into a requesting application (requestor) and request-receiving application (recipient). Since in two-way messaging each request generates a response, this process is reversed when the response message is sent. However, WSE only sees an incoming message as a request and an outgoing message as a response. Except where the X.509 certificates are concerned, configuring WSE for a client application is just about the same as for a Web service.

To configure WSE for your project:

1. Right-click the project in the Visual Studio "Solution Explorer" window and select "WSE Settings 2.0..." This displays the WSE Settings Tool (see Figure 3).
2. In the "General" tab, check both checkboxes to enable WSE for the Web service. (When enabling WSE for a client application, the ASP.NET checkbox will be grayed out.)
3. In the "Security" tab (see Figure 4), set "Store Location" to "localMachine" if the project is a Web service and to currentUser if the project is a client application.
4. To make X.509-based authentication work using test certificates, check "Allow Test Roots" and uncheck "Verify Trust" checkboxes in the "Security" tab (see Figure 4). (Note that you would never do this outside of development and test environments.)
5. Click "OK" to close the WSE Settings tool. WSE automatically modifies the appropriate configuration file for the application and adds Microsoft.Web.Services.dll to the list project references.

Once you have enabled WSE for both the Web service and client application, you are ready to program WSE to secure your request and response messages.

Programming WSE
With WSE configured, you can program the WSE runtime from your application. Just remember that with WSE enabled, all request messages must contain a security token that can be positively authenticated by WSE or else they will be immediately rejected. Also, when an incoming message is digitally signed or encrypted, if WSE cannot verify the signature or decrypt the message using either the attached security token or one that it has access to, it will reject the message. WSE handles both X.509-based security tokens and Username tokens out of the box. For other types of security tokens or to do your own custom authentication you will need to implement your own security token handler.

To make your code a bit easier to read, you should add the following C# using directives to your code:

• using Microsoft.Web.Services
• using Microsoft.Web.Services.Security
• using Microsoft.Web.Services.Security. Tokens

When programming a client application using the Visual Studio Add Web Reference tool to generate a proxy programming object that abstracts access to a Web service, WSE automatically generates a second proxy class for the referenced Web service. This class, appended with "Wse," inherits from the Microsoft.Web.Services. Web ServicesClientProtocol class that implements the RequestSoapContext and ResponseSoapContext properties, which are used to access the SoapContext objects for the incoming and outgoing SOAP messages. Make sure that you use the WSE-generated proxy class in your code or WSE will be bypassed.

Retrieving X.509 Certificates
When using X.509 certificates, you must tell WSE which certificates you want to use when it creates X.509-based security tokens. This is done using key identifiers, which are strings that uniquely identify X.509 certificates. You can use the X.509 Certificate Tool at design time to determine key identifiers, and while WSE can also do this at run time, it is much more complicated. I recommend storing the key identifier values for certificates required by your application in the configuration file using appSettings.add elements, like

<add key="clientPrivateKey" value="LptOGEbzc2HXS67ZSMsiNnrfDA0=" />

adding one for each certificate you need to use. This enables you to change certificates on the fly without having to recompile the application. Using key identifiers, WSE can easily create an X509Security Token object based on a specific X.509 certificate (see Listing 2).

Building the SoapContext for a Request Message
To secure a request message to a Web service using X.509 certificates, you must do the following:

1. Instantiate the Web service proxy object, which should be prefixed by "Wse" and inherits from Microsoft.Web.Services. WebServicesClientProtocol.
2. Get the RequestSoapContext property of the Web service proxy object.
3. Add an X509SecurityToken object (created in Listing 2) to the Security.Tokens collection of the request SoapContext.
4. To digitally sign the request, add a new Signature object to the Security.Elements collection of the request SoapContext. This Signature object is created using the same X509SecurityToken object added in step 3, assuming that this token supports digital signatures. You can determine if a token can be used for encryption by checking the object's SupportsDataEncryption property. WSE will generate a digital signature over the message body using the X.509 certificate, and it will add the signature information to a new Signature element in the Security header of the request message (Listing 1).
5. To encrypt the request, add a new EncryptedData object to the Security.Elements collection of the request SoapContext. This EncryptedData object is created using an X509SecurityToken object that instead represents the service's public key, which is different from the one added in step 3. You can still use the code in Listing 2 to create this token, but you will need to use the service certificate's key identifier instead of the one for the client certificate. Of course, the token must also support encryption, and you can determine if a token can be used for encryption by checking the object's SupportsDataEncryption property. WSE will encrypt the message body using the public key in the service's X.509 certificate and place the encrypted data inside an EncryptedData element in the body of the request message (Listing 1).

Listing 3 shows how these security objects are in turn added to the SoapContext for a request message to a Web service. In this example, myTokens[0] represents the client's token and myTokens[1] represents the service's token. Based on the code in this listing, WSE generates the SOAP request message in Listing 1.

Handing Incoming Requests
While X.509-based authentication can be tedious to configure (see the WSE 2.0 SDK documentation for troubleshooting potential error messages), it does make things easier to handle on the receiver-side of the exchange. For example, when an incoming message contains an X.509-based security token, WSE automatically attempts to authenticate the requestor by validating the certificate chain and looking for a corresponding certificate in the server's Machine Store. If it finds the certificate there, it passes the request on to the requested resource. Likewise, WSE automatically uses the attached certificate to validate any attached digital signatures, and it will also try to decrypt messages using the private key portion of the certificate used to encrypt the message, if it can find it. If you plan to use a non-X.509 authentication scheme, you will need to write a custom security token manager to authenticate other security tokens.

Conclusion
WS-Security provides the facilities necessary for securing SOAP messaging. However, other specifications like WS-Trust, WS-SecureConversation, WS-SecurityPolicy, and WS-Federation have been proposed to build even more robust and functional security scenarios. Out-of-the-box, WSE provides an immediate security benefit by blocking all request messages that cannot be authenticated and that contain invalid digital signatures or encryption. With a little effort, WSE can be configured to provide much-needed security for .NET Web services, and this is particularly true when using X.509 certificates. Note: The sample code shown in this article is from my book; you should be able to download it from the Microsoft Press Web site (www.microsoft.com/mspress/books/6708.asp).