Security by Design

CoverStory

LANGUAGES: C#

ASP.NET VERSIONS: 1.0 | 1.1

Securityby Design

Build Secure Web Services with WS-Security

By Jeffrey Hasan

Many companies have not adopted the Web servicestechnology because it lacks a security specification that can ensure theintegrity of transmitted messages and data. The WS-Security specification is a jointeffort by several vendors to address this important issue.

What do we actually mean when we talk about security ? Inbroad terms, we are talking about authentication and authorization:

Together, authentication and authorization provide for asecurity model by allowing you to identify a user and then give them selectiveaccess to resources.

Currently, it is possible to secure SOAP communicationsover HTTP using the certificate-based Secure Sockets Layer (SSL) protocol. SSLprovides encryption and digital signing of both SOAP messages and standard HTTPrequests and responses. But SSL has two major limitations that make itunsuitable for securing Web services communications within a service-orientedapplication. First, SSL is designed for point-to-point communication. However,service-oriented Web services may exchange SOAP messages between two or moreendpoints, and so they require a security solution that supports hops acrossmultiple endpoints and multiple domain boundaries. Second, the SSL protocol isbuilt on the HTTP protocol. Web services technology is transport-neutral, andsupports message exchange across different protocols, including TCP and SMTP,in addition to HTTP. The SSL protocol is simply too limiting for Web servicestechnology.

The WS-Security specification is designed to overcomethese limitations and provide an extensible security implementation that willevolve as the Web services technology becomes more sophisticated.

The WS-Security Specification

The prime currency in Service Oriented Architecture (SOA)applications are SOAP messages, because they are the means by which requestsare made and responses are received from Web service methods. The WS-Securityspecification provides a way for you to protect the integrity andconfidentiality of messages and to implement authentication and authorizationmodels in your Web services. The WS-Security specification enables you toimplement the following protections in your Web service calls:

The WS-Security specification is platform-independent andtransport-neutral, as are all the other WS specifications. Security informationis generated by the client and stored within the envelope of the SOAP requestmessage. The Web service in turn will deserialize this information, verify itsvalidity, and process the requested operation. In the event that the messagesecurity does not pass verification, the Web service will return a SOAP faultback to the client.

Web Services Enhancements (WSE) 2.0 provides the API forimplementing WS-Security in .NET-based Web services and client applications. TheAPI allows you to write code to format secured SOAP request messages in theclient and process secured messages within a Web service.

Implement WS-Security Using WSE 2.0

The focus of this article is to show you how to write thecode to implement WS-Security in Web services and their client applications. Wewill look at two examples:

1)       Digitally sign a SOAP request message with anX.509 certificate.

2)       Encrypt a SOAP request message with an X.509certificate.

Note that WSE 2.0 must be properly installed and configuredfor the sample projects to work.

The WSE 2.0 sample projects ship with test certificatesand keys, which we will use here because they are convenient. Here are theinstallation steps for the sample certificates that ship with WSE 2.0:

1)       Open the MMC console and add the Certificatessnap-in for both Current User and Local Machine.

2)       Open the Personal folder of the Current Usercertificate store and import the sample personal information exchange fileentitled Client Private.pfx. This is the private key that the Web serviceclient will use to encrypt requests to the Web service.

3)       Open the Personal folder of the Current Usercertificate store and import the sample test certificate entitled ServerPublic.cer. This is the public key that the client uses to digitally signrequests for the Web service.

4)       Open the Personal folder of the Local Machinecertificate store and import the sample test certificate entitled ServerPublic.cer. This is the public key that the Web service uses to decrypt theclient s request.

After the certificates are installed, you re ready tocreate Web service clients and services that exchange digitally signed andencrypted SOAP requests. (Note that SOAP responses may also be encrypted;however, that topic is beyond the scope of this article.)

How to Digitally Sign SOAP Messages

A digital signature is essentially a cryptographic hashthat is added to a SOAP message, and is based on a security token. Digitalsignatures may be generated using several token types, including an X.509 certificate.The certificate is used to generate a pair of related keys, called the privateand public keys. The private key is known only to the client and is used forthe following purposes:

The public key is made available to authorized services,which use it for the following purposes:

The digital signing process with X.509 certificates worksas follows:

1)     Theclient obtains an X.509 certificate and generates a private-public key pair.The service receives a copy of the public key.

2)     Theclient applies a hash algorithm to the message, which creates a so-calledmessage digest.

3)     Theclient then encrypts the message digest with their private key, which createsthe digital signature.

4)     Theclient attaches the digital signature to the SOAP request message.(Programmatically, WSE performs steps 3 and 4 together.)

5)     Theclient sends the SOAP request message out to the service.

6)     Theservice receives the SOAP message and checks the security token type.

7)     Afterthe service determines that an X.509 certificate was used, it decrypts themessage signature using the public key. This process allows the service toretrieve the original message hash. If the decryption process fails, then theservice assumes that the client is not the original sender of the message, orthe message has been tampered with, and a SOAP exception is raised.

8)     Theservice then generates its own message digest using the same algorithm that theclient used.

9)     Theservice compares its generated message digest against the one that has beenobtained from the client. If the two message digests match, then the signaturehas passed verification. If it does not, then the service assumes that themessage has been tampered with and a SOAP exception is raised.

Digital signatures can have real consequences on messagedelivery if they are not applied correctly, or if the verification processfails, because either of these issues will prevent the service from processingthe incoming SOAP request message. In addition, certificates will expire, soverification will fail if the certificate is not current. The X509SecurityTokenand X509SecurityCertificate classes both provide a Boolean IsCurrent propertythat verifies whether a given certificate is still valid.

Implement a Web Service that Accepts Digitally SignedRequests

Now let s look at an example Web service and client thatimplement digital signatures. The full code listing is available for download (seeend of article for details), so to preserve space I ll simply highlight partsof the code. Consider a Web service that provides stock ticker information. Figure1 shows the required Web.config file settings for the Web service.

    type="Microsoft.Web.Services2.Configuration.

    WebServicesConfiguration,Microsoft.Web.Services2,

     Version=2.0.0.0, Culture=neutral,PublicKeyToken=

    31bf3856ad364e35"/>

        WebServicesExtension,Microsoft.Web.Services2,

        Version=2.0.0.0,Culture=neutral, PublicKeyToken=

        31bf3856ad364e35"priority="1" group="0" />

      "StockTrader.CustomUsernameTokenManager,

       StockTraderSecure"xmlns:wsse=

       "http://docs.oasis-open.org/wss/2004/01/

       oasis-200401-wss-wssecurity-secext-1.0.xsd"

       qname="wsse:UsernameToken"/>

 allowRevocationUrlRetrieval="false"verifyTrust="false" />

Figure 1:Web.config settings for the secure Web service project.

The element contains a sub-element that registers a custom manager class for processing securitytokens. It also contains a sub-element called with attributes thatallow this project to use unverified test root certificates. Without thissetting your Web service calls will generate a SOAP exception alerting you thatyour certificate is not valid. The element also contains animportant attribute called storeLocation, which specifies the location of thecertificate that is used to validate or decrypt incoming requests.

Modify the Web Service to Process Signed SOAP Messages

The Web service must be modified to iterate through thecollection of signatures and tokens that are assigned to a SOAP requestmessage. It is in fact possible to add multiple tokens and signatures to a singlemessage, although the code listings shown here do not do this. The Web serviceshould process the signed SOAP message as follows:

1)     Loopthrough the collection of signatures attached to the SOAP message.

2)     Foreach signature in the collection, determine on which type of token it is based.

3)     Forusername tokens, implement a custom token manager to validate the token.

Figure 2 shows you how to loop through the collection ofsignatures and tokens attached to a SOAP request message. Note that this codelisting is implemented directly inside the RequestQuote Web method so that aSOAP fault may be raised directly from the method should the user fail to beauthenticated or authorized to access the method.

using System.Web;

using System.Web.Services;

using System.Web.Services.Protocols;

using System.Web.Services.Description;

using System.Xml.Serialization;

using Microsoft.Web.Services2;

using Microsoft.Web.Services2.Security;

using Microsoft.Web.Services2.Security.Tokens;

using System.Security.Permissions;

using StockTraderTypes;

[WebService()]

public class StockTraderService :

 System.Web.Services.WebService,IStockTrader

{

  [WebMethod()]

 public override QuoteRequestQuote(string Symbol)

 {

// Initialize the custom token manager, in case it's needed

 CustomUsernameTokenManagerobjMgr =

   newCustomUsernameTokenManager();

// Verify the signature on the Web service

// request to this method

 bool SignatureIsValid =false;

 SoapContextrequestContext =

   RequestSoapContext.Current;

   foreach (ISecurityElementobjElem in

            requestContext.Security.Elements)

   {

     if (objElem isMessageSignature)

     {

       MessageSignatureclientSignature =

          (MessageSignature)objElem;

   if(clientSignature.SigningToken is X509SecurityToken)

       {

       SignatureIsValid =true;

       }

   else if(clientSignature.SigningToken is UsernameToken)

       {

       SignatureIsValid =true;

       objMgr.VerifyToken(clientSignature.SigningToken );

       }

     }

   }

// Proceed with request if signature is valid

 Quote q = new Quote();

 if (SignatureIsValid) {}

// Implementation code for RequestQuote()

 }

 return q;

}

Figure 2: Loopthrough the collection of signatures and tokens attached to a SOAP requestmessage.

Create the Web Service Client

Now let s write a Web service client that generates signedSOAP request messages. Figure 3 shows the portion of the code that retrieves anX.509 certificate and applies it to a SOAP request message as a digitalsignature.

using Microsoft.Web.Services2.Security;

using Microsoft.Web.Services2.Security.Tokens;

using Microsoft.Web.Services2.Security.X509;

X509CertificateStore store;

X509SecurityToken token;

// Open the CurrentUser Certificate Store

store = X509CertificateStore.CurrentUserStore(

 X509CertificateStore.MyStore);

// Retrieve the X509 certificate from the

// CurrentUserStore certificate store

string ClientBase64KeyId ="gBfo0147lM6cKnTbbMSuMVvmFY4=";

X509CertificateCollection certs =

 store.FindCertificateByKeyIdentifier(

 Convert.FromBase64String(ClientBase64KeyId ) );

if (certs.Count > 0)

{

 // Get the firstcertificate in the collection

 token = newX509SecurityToken(

    ((X509Certificate)certs[0]) );

}

// Add the token and digital signature to the

// SOAP request message

serviceProxy.RequestSoapContext.Security.Tokens.Add( token );

serviceProxy.RequestSoapContext.Security.Elements.Add(

 new MessageSignature(token ) );

// Send the Web service request via the proxy class

// (Code listing not shown here.)

Figure 3:Digitally sign a Web service request using an X.509 certificate.

Encrypt SOAP Messages with an X.509 Certificate

Security tokens and digital signing allow you to identifya service requestor, and to determine whether a request message has beentampered with, but they do nothing to protect the contents of a SOAP messagefrom network sniffers. Encryption technology enables you to generate acryptographic hash of the SOAP message for transport, and to decrypt themessage contents at the receiving end.

There are two kinds of encryption:

Interestingly enough, when a SOAP message is encrypted,only the body of the message gets hashed. If your SOAP message includes customSOAP header values, then you must encrypt them separately. In the followingsection we ll review how to encrypt the body of a SOAP message using asymmetricencryption.

To get started, you can implement asymmetric encryption asoutlined in the following steps:

1)     Generatea private-public key pair based on a digital certificate.

2)     Installthe private key in the client s local certificate store.

3)     Installthe public key in the server s local certificate store.

4)     Implementcode in the Web service client to generate an encrypted SOAP request message.

Implement the Web Service Client

The client code for generating encrypted SOAP requestmessages is very similar to the code for digitally signing messages. The clientretrieves the applicable X.509 certificate-based private key from its personalcertificate store and then uses this key to generate a hash of the SOAPmessage. Figure 4 shows you the required code.

public void EncryptRequestUsingX509Certificate()

{

// Retrieve the X509 certificate from the

// CurrentUserStore certificate store

X509SecurityToken token;

string ClientBase64KeyId ="gBfo0147lM6cKnTbbMSuMVvmFY4=";

// Open the CurrentUser Certificate Store

X509CertificateStore store;

store = X509CertificateStore.CurrentUserStore(

 X509CertificateStore.MyStore);

// Find the certificate based on the server's

// base64 key identifier

X509CertificateCollection certs =

 store.FindCertificateByKeyIdentifier(

 Convert.FromBase64String(ClientBase64KeyId ) );

if (certs.Count > 0)

{

 // Get the firstcertificate in the collection

 token = newX509SecurityToken(

    ((X509Certificate)certs[0]) );

}

if (token == null) throw new ApplicationException(

 "Unable to obtainsecurity key.");

StockTraderServiceWse serviceProxy =

 newStockTraderServiceWse();

// Add the certificate key to encrypt the request

serviceProxy.RequestSoapContext.Security.Elements.Add(

 new EncryptedData( token) );

// Call the Web service RequestQuote() method

Console.WriteLine("Calling {0}", serviceProxy.Url);

WSStockTraderClient.StockTraderEncrypted.Quote strQuote =

 serviceProxy.RequestQuote("MSFT");

// Results

Console.WriteLine("Web Service call successful.Result:");

Console.WriteLine( " " );

Console.WriteLine( "Symbol: " + strQuote.Symbol );

Console.WriteLine( "Price:  " + strQuote.Last );

Console.WriteLine( "Change: " +

                   strQuote.PercentChange +"%");

}

Figure 4: Encrypta SOAP request message using an X.509 certificate.

Certificate-based keys must be retrieved from thecertificate store using their base64 key identifier. WSE 2.0 ships with auseful utility called the WSE X.509 Certificate Tool, which allows you tobrowse certificates for the Current User and Local Machine certificate stores,and to retrieve base64 key identifier information. Figure 5 shows the tooldisplaying the client private key certificate that is used in the example shownin Figure 4.

Figure 5: The WSE X.509 CertificateTool.

Modify the Web Service to Process Encrypted SOAP Messages

For asymmetric encryption, the Web service does notrequire additional code for processing encrypted SOAP request messages. Youmust simply ensure that the public key for decryption is installed in the LocalMachine certificate store on the same server where the Web service isinstalled. If the public key is not installed correctly, the client applicationwill receive a SOAP fault indicating a problem on the receiving end. But if thecertificates are installed correctly, the WSE 2.0 handlers will automaticallydecrypt the incoming request for you.

From a procedural standpoint you may still want to put codein place in the Web method to verify that the request message is in factencrypted. Figure 6 shows the policy-oriented code listing for verifying thatan incoming request message is encrypted.

bool EncryptionIsValid = false;

SoapContext requestContext = RequestSoapContext.Current;

foreach (ISecurityElement objElem in

        requestContext.Security.Elements)

{

 if (objElem isEncryptedData)

 {

    // Encrypted Dataexists in the Element collections.

    // Now check if it isthe body that was encrypted.

    EncryptedData encData= objElem as EncryptedData;

    if(encData.TargetElement.LocalName == "Body")

    {

       EncryptionIsValid =true;

       // Process the Webservice request (code not shown)

    }

 }

}

Figure 6: Code toverify that an incoming request message is encrypted.

Conclusion

This article has demonstrated how to use WSE 2.0 and theWS-Security specification to implement several types of security measures inSOAP messages, including:

Thesample code referenced in this article is available for download.

Jeffrey Hasan is presidentof Bluestone Partners, Inc., an IT solutions company based in Orange County, CA(http://www.bluestonepartners.com).Jeff is an experienced enterprise architect and .NET developer, and is the co-authorof several books and articles on .NET technology, including the just-released Expert Service Oriented Architecture in C#: Using theWeb Services Enhancements 2.0 (Apress, 2004). Contact Jeff at mailto:[email protected].