WS-Security: Web services the secure way

• Download source files - 7.57 Kb

What is WS-Security

Although web services are generally a good idea, they lack some practical features. For example, systemized security and authentication support.

If developers would like to have their web services authenticated, they must write and implement it themselves. Also confidentiality of communication is not guaranteed, if SSL is not in use.

Because none of them is too enjoyable, good folks from Microsoft, IBM and VeriSign created the WS-Security standard, which solves three basic problems:

• Authentication and authorization of users – along with web service call, you can now pass authentication information, login and password. These values are automatically processed at server side.
• Message integrity – messages can be digitally signed, which eliminates the possibility to modify them on the way.
• Message encryption – SOAP messages can be encrypted, even when sent via non-encrypted channel such as HTTP, to ensure privacy.

How WS-Security works

WS communication between client and server is made by exchange of SOAP messages, which are in fact normal XML documents. These are transported via HTTP or HTTPS in most cases.

Use of XML allows almost unlimited extension of these messages – and that’s exactly what WS-Security does. It adds further elements, which can contain various security related information.

Web Service enhancements

The WS-Security protocol is not included in current version of the .NET framework. But there is a package named “Web Service Enhancements” (WSE), which can be downloaded for free from the Microsoft’s web site. This extension implements some advanced standards, besides the WS-Security mentioned here, also WS-Routing, WS-Attachments and DIME.

The current stable version is 1.0 SP1 for .NET framework 1.0 or 1.1 (version without SP1 is intended for .NET framework 1.0 only). Newly available is also “technology preview” of version 2.0, which offers even more features, like role-based authorization and protocols WS-Policy, WS-SecurityPolicy, WS-Trust, WS-SecureConversation and WS-Addressing.

After installing WSE, you would be ale to use classes contained in namespace Microsoft.Web.Services.

All following code has been developed in VS.NET 2003 using WSE 1.0 SP1 and tested on IIS 6.0. Custom classes are intended to be in namespace AltairCommunications.Artex.

Authentication

Server

To use authentication, you must create a class, implementing the Microsoft.Web.Services.Security.IPasswordProvider interface. It must contain method GetPassword, which would return plaintext password for specified user.

The following is a trivial implementation, which returns the string “password”. In real world you would probably search some kind of user database.

Public Class MyPasswordProvider _
 Implements Microsoft.Web.Services.Security.IPasswordProvider

 Public Function GetPassword(ByVal token As _
 Microsoft.Web.Services.Security.UsernameToken) As String _
 Implements _
 Microsoft.Web.Services.Security.IPasswordProvider.GetPassword

     Return "password"
 End Function
End Class

A second thing you need to do is to setup Web.Config. It must tell your application that it should use your class to check passwords. WARNING: The example has added line breaks for readability. Attribute values must be on single line.

<?xml version="1.0" encoding="utf-8" ?>
<configuration>
    <configSections>
     <section name="microsoft.web.services" 
       type="Microsoft.Web.Services.Configuration.WebServicesConfiguration, 
         Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral, 
         PublicKeyToken=31bf3856ad364e35" />
    </configSections>
    <system.web>
        <webServices>
            <soapExtensionTypes>
              <add type="Microsoft.Web.Services.WebServicesExtension, 
                  Microsoft.Web.Services, Version=1.0.0.0, Culture=neutral, 
                  PublicKeyToken=31bf3856ad364e35"
                priority="1" group="0" />
            </soapExtensionTypes>
        </webServices>
    </system.web>
    <microsoft.web.services>
        <security>
            <passwordProvider 
                type="AltairCommunications.Artex.MyPasswordProvider, 
                      AltairCommunications.Artex" />
        </security>
    </microsoft.web.services>
</configuration>

At this moment, all web service requests containing authentication information would be checked for their validity and in case of error refused automagically.

The web services methods itself can be written the usual way. Only it is recommended to add at beginning a test, a check if user is authenticated (to allow publishing of anonymous methods too, WSE will let go through, request without any authentication information). At this time, you would probably want also to check, if the web service is called via the SOAP protocol, not by simply using HTTP GET or POST, which cannot implement WS-Security.

Secured (and personalized) version of well-known HelloWorld may then look like the following:

<WebMethod()> Public Function SecureHello() As String 
    '-- Check if I am called via SOAP
    Dim RC As Microsoft.Web.Services.SoapContext = _
      Microsoft.Web.Services.HttpSoapContext.RequestContext
    If RC Is Nothing Then Throw New _
        System.Web.Services.Protocols.SoapException_
        ("Only SOAP requests are accepted", _
        New System.Xml.XmlQualifiedName("NotSoapCall"))

    '-- Load user authentication data
    Dim U As Microsoft.Web.Services.Security.UsernameToken = GetUser(RC)
    If U Is Nothing Then Throw New _
      System.Web.Services.Protocols.SoapException_
        ("You are not authenticated", _
        New System.Xml.XmlQualifiedName("NotAuthenticated"))

    '-- Return personalized message
    Return "Hello, " & U.UserName
End Function

Private Function GetUser(ByVal C As _
    Microsoft.Web.Services.SoapContext) _
    As Microsoft.Web.Services.Security.UsernameToken
    
    For Each T As Microsoft.Web.Services.Security.SecurityToken _
                                           In C.Security.Tokens
        If TypeOf T Is Microsoft.Web.Services.Security.UsernameToken _
                           Then Return T
    Next
    Return Nothing
End Function

Client

Calling of secured WS is similar to normal. WSE in VS.NET would generate a web service proxy, which would contain two versions of classes: standard (inherits System.Web.Services.Protocols.SoapHttpClientProtocol) and secure (inherits Microsoft.Web.Services.WebServicesClientProtocol and has added “Wse” to end of name).

Client must generate instance of Microsoft.Web.Services.Security.UsernameToken, which would contain authentication data, and send it along with call:

Const USER_NAME As String = "user"
Const USER_PASS As String = "password"

Dim T As New TestWSE.SecureWSWse

Dim U As New Microsoft.Web.Services.Security.UsernameToken( _
    USER_NAME, _
    USER_PASS, _
    Microsoft.Web.Services.Security.PasswordOption.SendHashed)
T.RequestSoapContext.Security.Tokens.Add(U)

Console.WriteLine T.SecureHello()

Digital signatures

The above solution can pass authentication, but does not ensure integrity of data – message can be changed during transport. To avoid this, you must add digital signature to the message – which is simple, as well:

Server

There is no need to configure anything at the server. Only when you want to check if message is signed or not, you can use the following function:

Private Function IsSigned(ByVal C As Microsoft.Web.Services.SoapContext) _
                                                       As Boolean
    For Each E As _
      Microsoft.Web.Services.Security.ISecurityElement In C.Security.Elements
        If TypeOf E Is _
           Microsoft.Web.Services.Security.Signature Then Return True
    Next
    Return False
End Function

Client

At client side, you must add only one line of code, which would add the signature:

Const USER_NAME As String = "user"
Const USER_PASS As String = "password"

Dim T As New TestWSE.SecureWSWse

Dim U As New Microsoft.Web.Services.Security.UsernameToken( _
    USER_NAME, _
    USER_PASS, _
    Microsoft.Web.Services.Security.PasswordOption.SendHashed)
T.RequestSoapContext.Security.Tokens.Add(U)

T.RequestSoapContext.Security.Elements.Add( _
    New Microsoft.Web.Services.Security.Signature(U))

Console.WriteLine T.SecureHello()

Data encryption

In this phase, all communication is authenticated and digitally signed, which secures it against a counterfeit. But all data are transported in clear form and everyone who understands the SOAP protocol can read them. There are two ways to change this situation.

First is to use secured transport channel for communication. You must setup web server to use HTTPS instead of HTTP. This solution is not always possible and wanted. It’s why you can use encryption of the SOAP messages itself, while sending them through an open communication channel.

Server

We will use the 3DES symmetric algorithm to encrypt message contents. Thus, both parties need to have the same encryption key. In the following example we would use 128 bit key, which means 16 bytes, represented as ASCII string MY_SECRET_KEY_16.

The technique is similar to password provider class above. Now we need to implement interface Microsoft.Web.Services.Security.IDecryptionKeyProvider. Example is here.

Public Class MyDecryptionKeyProvider
Implements Microsoft.Web.Services.Security.IDecryptionKeyProvider

Public Function GetDecryptionKey(ByVal algorithmUri As String, _
     ByVal keyInfo As System.Security.Cryptography.Xml.KeyInfo) _
     As Microsoft.Web.Services.Security.DecryptionKey _
     Implements _
     Microsoft.Web.Services.Security.IDecryptionKeyProvider.GetDecryptionKey
    
    Return New Microsoft.Web.Services.Security.SymmetricDecryptionKey( _
        System.Security.Cryptography.TripleDES.Create(), _
        System.Text.Encoding.ASCII.GetBytes("MY_SECRET_KEY_16"))
    End Function
End Class

Also the key provider must be registered in Web.Config. To section /configuration/microsoft.web.services/security add element passwordProvider:

<passwordProvider 
 type="AltairCommunications.Artex.MyPasswordProvider, 
 AltairCommunications.Artex" />

For comfort of a kind reader, here is function IsEncrypted, which can check if conversation was encrypted or not:

Private Function IsEncrypted(ByVal C As _
          Microsoft.Web.Services.SoapContext) As Boolean
    For Each E As Microsoft.Web.Services.Security.ISecurityElement _
                                             In C.Security.Elements
        If TypeOf E Is _
           Microsoft.Web.Services.Security.EncryptedData Then 
              Return True
    Next
    Return False
End Function

Client

To allow data encryption, also the client part must have proper encryption key. Possible implementation can look like this:

Const USER_NAME As String = "user"
Const USER_PASS As String = "password"

Dim T As New TestWSE.SecureWSWse

Dim U As New Microsoft.Web.Services.Security.UsernameToken( _
    USER_NAME, _
    USER_PASS, _
    Microsoft.Web.Services.Security.PasswordOption.SendHashed)
T.RequestSoapContext.Security.Tokens.Add(U)

T.RequestSoapContext.Security.Elements.Add( _
    New Microsoft.Web.Services.Security.Signature(U))

Dim Key As New Microsoft.Web.Services.Security.SymmetricEncryptionKey( _
    System.Security.Cryptography.TripleDES.Create(), _
    System.Text.Encoding.ASCII.GetBytes(Me.txtKey.Text))
Key.KeyInfo.AddClause(New System.Security.Cryptography.Xml.KeyInfoName)
T.RequestSoapContext.Security.Elements.Add( _
    New Microsoft.Web.Services.Security.EncryptedData(Key))

Console.WriteLine T.SecureHello()

Instead of happy end

Excellent tool to debugging is possibility to save all exchanged messages to files. Simply add the following to the microsoft.web.services section of Web.Config:

<microsoft.web.services>
    <diagnostics>
        <trace enabled="true" input="input.xml" output="output.xml" />
    </diagnostics>
</microsoft.web.services>

But be warned: do not forget to switch the tracing before deploying application to production server. Like all other XML based protocols, the SOAP is pretty gossipy and trace files can grow to incredible sizes.

Links

• WS-Security Specification.
• WSE 1.0 SP1
• WSE 2.0 Technology preview