Security by Design

    type="Microsoft.Web.Services2.Configuration.

    WebServicesConfiguration, Microsoft.Web.Services2,

     Version=2.0.0.0, Culture=neutral, PublicKeyToken=

    31bf3856ad364e35" />

      "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 security tokens. It also contains a sub-element called with attributes that allow this project to use unverified test root certificates. Without this setting your Web service calls will generate a SOAP exception alerting you that your certificate is not valid. The element also contains an important attribute called storeLocation, which specifies the location of the certificate 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 the collection of signatures and tokens that are assigned to a SOAP request message. It is in fact possible to add multiple tokens and signatures to a single message, although the code listings shown here do not do this. The Web service should process the signed SOAP message as follows:

1)     Loop through the collection of signatures attached to the SOAP message.

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

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

Figure 2 shows you how to loop through the collection of signatures and tokens attached to a SOAP request message. Note that this code listing is implemented directly inside the RequestQuote Web method so that a SOAP fault may be raised directly from the method should the user fail to be authenticated 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 Quote RequestQuote(string Symbol)

 {

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

 CustomUsernameTokenManager objMgr =

   new CustomUsernameTokenManager();

// Verify the signature on the Web service

// request to this method

 bool SignatureIsValid = false;

 SoapContext requestContext =

   RequestSoapContext.Current;

   foreach (ISecurityElement objElem in

            requestContext.Security.Elements)

   {

     if (objElem is MessageSignature)

     {

       MessageSignature clientSignature =

          (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: Loop through the collection of signatures and tokens attached to a SOAP request message.

Create the Web Service Client

Now let s write a Web service client that generates signed SOAP request messages. Figure 3 shows the portion of the code that retrieves an X.509 certificate and applies it to a SOAP request message as a digital signature.

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 first certificate in the collection

 token = new X509SecurityToken(

    ((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 identify a service requestor, and to determine whether a request message has been tampered with, but they do nothing to protect the contents of a SOAP message from network sniffers. Encryption technology enables you to generate a cryptographic hash of the SOAP message for transport, and to decrypt the message contents at the receiving end.

There are two kinds of encryption:

• Symmetric encryption. Also known as private-key, or shared-secret encryption, this method generates a cryptographic hash using a key that is known to both the sender and the receiver. Symmetric encryption is the least secure encryption method because both sender and receiver must share the same key, and so the encryption is only effective if the key remains secret.
• Asymmetric encryption. Also known as public-key encryption, this method generates a cryptographic hash based on a private key that is known only to the sender. The receiver is given a public key that will decrypt a message that was hashed with the corresponding private key. Asymmetric encryption is the most secure method, and there are many related encryption methodologies from which to choose, including SHA1 and Triple-DES.

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

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

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

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

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

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

Implement the Web Service Client

The client code for generating encrypted SOAP request messages is very similar to the code for digitally signing messages. The client retrieves the applicable X.509 certificate-based private key from its personal certificate store and then uses this key to generate a hash of the SOAP message. 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 first certificate in the collection

 token = new X509SecurityToken(

    ((X509Certificate) certs[0]) );

}

if (token == null) throw new ApplicationException(

 "Unable to obtain security key.");

StockTraderServiceWse serviceProxy =

 new StockTraderServiceWse();

// 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: Encrypt a SOAP request message using an X.509 certificate.

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

Figure 5: The WSE X.509 Certificate Tool.

Modify the Web Service to Process Encrypted SOAP Messages

For asymmetric encryption, the Web service does not require additional code for processing encrypted SOAP request messages. You must simply ensure that the public key for decryption is installed in the Local Machine certificate store on the same server where the Web service is installed. If the public key is not installed correctly, the client application will receive a SOAP fault indicating a problem on the receiving end. But if the certificates are installed correctly, the WSE 2.0 handlers will automatically decrypt the incoming request for you.

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

bool EncryptionIsValid = false;

SoapContext requestContext = RequestSoapContext.Current;

foreach (ISecurityElement objElem in

        requestContext.Security.Elements)

{

 if (objElem is EncryptedData)

 {

    // Encrypted Data exists in the Element collections.

    // Now check if it is the body that was encrypted.

    EncryptedData encData = objElem as EncryptedData;

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

    {

       EncryptionIsValid = true;

       // Process the Web service request (code not shown)

    }

 }

}

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

Conclusion

This article has demonstrated how to use WSE 2.0 and the WS-Security specification to implement several types of security measures in SOAP messages, including:

• Digital signatures on SOAP messages to detect message tampering.
• Encryption of SOAP messages (using asymmetric encryption) to protect the contents of a SOAP message from network sniffers.

The sample code referenced in this article is available for download.

Jeffrey Hasan is president of 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-author of several books and articles on .NET technology, including the just-released Expert Service Oriented Architecture in C#: Using the Web Services Enhancements 2.0 (Apress, 2004). Contact Jeff at mailto:[email protected].