Chapter 7 — WS-I BSP Interoperability Guidance

  • Article

 

Patterns and Practices home

WS-I Basic Security Profile 1.0 Reference Implementation: Preview release for the .NET Framework version 2.0

Microsoft Corporation

May 2006

Summary: Chapter 7 provides guidance on designing interoperable Web services according to the Basic Security Profile (BSP).

Contents

Basic Security Profile 1.0 Guidance
Summary

This chapter discusses how you can develop interoperable Web services, focusing on how the Sample Application supports interoperability. It looks at the requirements of the WS-I Basic Security Profile (BSP) 1.0 and how they can affect interoperability. It also examines some specific interoperability issues that have emerged during the development of the Sample Application.

Note: For more information about building interoperable Web services, see WSE 3.0 Security: Interoperability Considerations on MSDN at https://msdn.microsoft.com/practices/default.aspx?pull=/library/en-us/dnpag2/html/wss_appx_interopcons_wse30.asp.

Basic Security Profile 1.0 Guidance

The BSP 1.0 attempts to increase interoperability by addressing the most common problems that implementation experience has revealed to date; it does not provide a guarantee of interoperability between secured Web services.

It is important to note that the BSP 1.0 covers only the specifications contained in WS-Security, focusing on SOAP message security, in particular data integrity and confidentiality. Other specifications, such as WS-Addressing, WS-Trust, and WS-SecureConversation have not been fully and formally reviewed by standards organizations such as OASIS or W3C. As a result, it is possible that other vendors have not implemented all of these specifications or implemented them in the same manner as Microsoft, making interoperability unlikely with those platforms at this time.

Specifying Security Requirements

In many cases, the BSP 1.0 has very precise requirements that reduce the need for a service to expose its requirements to client applications. However, in other areas, the BSP 1.0 allows some flexibility and extensibility in the application of security to messages. This means that some agreement has to be reached over which mechanisms should be used for message exchange, including for the following areas:

  • Encrypted elements
  • Signed elements
  • Data encryption algorithms
  • Key encryption algorithms
  • Security tokens
  • Certificate extensions
  • Certificate issuers

Note: WSE 3.0 supports all the encryption algorithms mentioned in the BSP 1.0.

Before a client application can communicate with a secure Web service, it must know the service's security requirements. These requirements differ for request and response messages.

For request messages sent from a client to a service, the client needs to know the answers to the following questions:

  • Do request messages need to be signed to provide data integrity? If they do, what part of the message needs to be signed, and with what kind of token?
  • Should request messages be encrypted to provide confidentiality? If they should, what parts of the message should be encrypted, and with which token should it be encrypted?
  • What requirements are mandatory and which are optional?

For response messages sent from a service to a client, the service needs to know the answers to the following questions:

  • Do response messages need to be signed to provide data integrity? If they do, what part of the message needs to be signed and with what kind of token?
  • Should response messages be encrypted to provide confidentiality? If they should, what parts of the message should be encrypted, and with which token should it be encrypted?
  • What requirements are mandatory and which are optional?
  • How should SOAP Faults be secured?

The most logical way of specifying these requirements would be as an extension to the contract for the Web service, allowing client applications to understand the security requirements of a service using machine-readable policy. However, the Web service security stack incorporates a number of protocols, each of which are in various states of implementation by different vendors. No security policy description language or negotiation mechanism is in scope for the BSP, so much of security policy must be transmitted using out of band agreements.

The WS-I Sample Application Working Group uses a design document to communicate security requirements out of band. The design document specifies the exact requirements that each service must implement for request and response messages. These requirements specify data integrity and confidentiality requirements so that, for example, vendors know which parts of the message to sign and encrypt using which tokens.

Exchanging Security Tokens

In some cases, before an interaction, a client and a service may need to exchange security tokens with one another. For example, if a client needs to be authenticated using an X.509 certificate, both the client and the service must establish a common certificate authority (CA) that both trust. Or, if the client needs to encrypt a request, it will need a reference to the certificate containing the public key for the service.

As with specifying security requirements, the BSP 1.0 does not specify any mechanism for exchanging security tokens. The WS-Trust specification does provide a mechanism for exchanging security tokens dynamically, but because this is out of scope for the BSP 1.0, there is no guarantee of interoperability.

Interoperability Considerations for the Sample Application

During the development and testing of the Sample Application, the development team encountered a number of areas where specific actions needed to be taken to ensure interoperability. This section details those areas, and as such, it is not intended to be a complete description of interoperability issues covered by the BSP. The only security tokens currently used by the Sample Application are X.509 and user name tokens.

Note: The Sample Application is not designed to cover every aspect of the BSP. The test tools are designed to provide broader coverage of the BSP.

X509 Certificates

Oasis has released errata for the X509 token profile that, among other changes, modifies the way in which X509 tokens are referenced. However, the document was not normative, so it should not be implemented by vendors.

In some cases, vendors did implement these errata, which have caused some interoperability issues. The following references to X.509 tokens should be included in secure messages.

  • BinarySecurityToken/@ValueType="....#X509v3"
  • KeyIdentifier/@ValueType="....@X509SubjectKeyIdentifier"

However, if the errata are incorrectly implemented, the following references are included:

  • BinarySecurityToken/@ValueType="....#X5093"
  • KeyIdentifier/@ValueType="....@X509v3SubjectKeyIdentifier"

If the service you are consuming uses the Oasis errata, you should be able to contact product support for that vendor and request a service pack to address this issue.

Note: WSE 3.0 has not implemented the errata.

Verification of WS-Addressing Headers

WSE policy that is generated by Visual Studio 2005 requires that if a WS-Addressing header is present, it must be signed. If a WS-Addressing header is not present, no error is generated.

Note: The W3C currently classifies the WS-Addressing specification as a proposed recommendation.

Mapping Security Policy to a Web Service Operation

Most vendors have implemented some declarative mechanism for describing security requirements. This reduces the need for developers to have to understand a complex set of APIs that, if used incorrectly, may result in an insecure application. WSE 3.0 allows security policy to be specified declaratively for all the services within an application, or for a particular service, or for a particular operation on a service.

The ability to map security policy to an operation on a service currently results in several interoperability issues. WSE supports this capability through the requestAction attribute in the protection element of each assertion or programmatically with the MessageProtectionRequirements class.

Not all vendors currently implement WS-Addressing. As a result, you might want to apply the same security policy across all operations on a service. However, if there are two operations that have different security requirements, you should consider splitting the operations into separate Web services or using the .requestAction attribute.

If you are specifying security for your Web services using policy — which is a good practice — and you have distinct security requirements for operations within a service, you might want to test the operation of your Web service without the Web service addressing headers to ensure the policy functions correctly without the headers. To do this, you have to define a custom filter that removes WS-Addressing headers from outgoing messages, as shown in the following code example.

// This is a WSE filter that removes WSA headers from output messages.
using System;
using System.Xml;
using Microsoft.Web.Services3;
using System.Collections;
namespace CustomFilterLibrary
{
    // Class derives from the SoapOutputFilter class.
    public class RemoveWSAHeadersFilter: SoapFilter
    {
        public RemoveWSAHeadersFilter()
        {
            // This is an empty constructor.
        }
        // Override the ProcessMessage method.
        public override SoapFilterResult ProcessMessage(SoapEnvelope envelope)
        {
            if (envelope == null)
                throw new ArgumentNullException("No envelope!");
            for (int loop=envelope.Header.ChildNodes.Count - 1; loop>=0; loop--)
            {
                if (envelope.Header.ChildNodes[loop].NamespaceURI == 
Microsoft.Web.Services3.Addressing.WSAddressing.NamespaceURI)
                    envelope.Header.RemoveChild(envelope.Header.ChildNodes[loop]);
            }
return SoapFilterResult.Continue;
        }
    }
}

Custom filters must be defined toward a policy assertion. To do this, you must create a policy assertion. When the assertion is executed, the WSE engine asks the assertion to return Input/Output filters for both the service and the client.

In the preceding code, only output filters have to be returned. For more information, see "How to: Migrate Custom Filters to Custom Policy Assertions" on MSDN at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/wse3.0/html/4ffe5169-ec97-47ae-9df8-0bca49421777.asp.

You also have to create a policy assertion. When the policy assertion is executed, the WSE engine requires the assertion to return input and output filters for both the service and the client. The following code shows the policy assertion.

public class RemoveWSAHeadersFilterAssertion : PolicyAssertion
{
public override SoapFilter CreateServiceInputFilter(FilterCreationContext context)
{
    return new RemoveWSAHeadersFilter ();
}
}

This policy assertion can be added to policies either declaratively or programmatically. For more information, see Chapter 5, "Policy Usage in the Sample Application."

UsernameToken

UsernameToken is used as a security token by the Sample Application. When the UsernameToken is used without a password, the nonce and created date fields are optional. However, WSE 3.0 assumes the fields will always be there because WSE 3.0 always provides the values regardless of whether the password is provided.

A basic form of replay detection is implemented in WSE 3.0 when using UsernameToken as a security token. The following code shows this functionality enabled.

<microsoft.web.services3>
    <security> 
      <securityTokenManager>

        <add localName="UsernameToken" type="Microsoft.Web.Services3.Security.Tokens.UsernameTokenManager, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" priority="1" group="0" namespace="https://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd"/>
         
 <replayDetection enabled="true" windowInSeconds="300" />
        
        </add>

      </securityTokenManager>
    </security>
 </microsoft.web.services3>

If the incoming UsernameTokens do not contain a nonce and created date fields, the replay cache within WSE 3.0 will not function, so in this case you should not enable replay detection. Alternatively you can use the signature digest in place of the nonce.

Message Age and Clock Skew

The timestamp within a secure message is often critical to an effective replay detection strategy because it can be used to limit the number of items that need to be cached when checking for a replay attack.

WSE includes a setting that determines how long a message is valid for after creation. The <defaultTtlInSeconds> element specifies the number of seconds after creation that every outgoing SOAP message is valid. The default value is 5 minutes, but the WS-I SCM architecture document recommends that this is set to 900 seconds (15 minutes).

To reject messages reliably, you must ensure that clocks on the sending and receiving servers are synchronized. Clocks of client and server computers must be synchronized to prevent messages from being rejected unduly. However, because not all vendors have the ability to ensure that their clocks are synchronized with Internet time services, WSE 3.0 has a clock skew setting that allows you to specify a tolerance factor for time synchronization. The <timeToleranceInSeconds> setting corresponds to the acceptable time difference (clock skew) between the sender and the recipient of a message. By default, it is configured to 300 seconds or 5 minutes. However, you can change this value in the service's Web.config file if you require a different value. The WS-I SCM Architecture document recommends that this is set to 900 seconds (15 minutes).

The <timeToleranceInSeconds> setting is shared, so changing it may also affect security token managers and other policy assertions operating in the same virtual directory as the service.

While the clock skew function can help with interoperability, reducing the need for clock synchronization effectively reduces the security of your environment. Therefore, wherever possible, you should use Internet time services to ensure that your clocks are synchronized and remove the need for significant clock skew.

Basic Security Profile Detailed Review

For a detailed analysis of the Basic Profile (BP) 1.0, including the compliance of ASMX to the BP 1.0, see Building Interoperable Web Services: WS-I Basic Profile 1.0 on MSDN at https://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnsvcinter/html/wsi-bp_msdn_landingpage.asp. Note that this study will not be completed for BSP 1.0 until the BSP is finalized, and it will be performed only if there is sufficient customer demand.

Summary

To ensure that your Web services interoperate with the Sample Application, you must understand how the Sample Application supports interoperability. This chapter has examined how the requirements of the BSP 1.0 can affect interoperability with the Sample Application. It also examined some of the specific interoperability issues that emerged during the development and testing of the Sample Application.

Start | Previous | Next

Patterns and Practices home