How to: Encrypt a SOAP Message by Using a User Name and Password

Article
09/15/2006

The following procedures detail how to use policy or code to encrypt a SOAP message by using a user name and password.

To use policy to encrypt a SOAP message by using a user name and password

Define a policy assertion and encryption requirements by adding <Policy> Element (WSE for Microsoft .NET) (1) and <Confidentiality> Element elements.
1. Add a <Policy> Element (WSE for Microsoft .NET) (1) element to the policy file for the application. Add the <Policy> Element (WSE for Microsoft .NET) (1) element as a child element of the <policies> Element element.
  The <Policy> Element (WSE for Microsoft .NET) (1) element defines criteria that a SOAP message must meet. The criteria are specified as child elements of the <Policy> element. The Id attribute value provides a name that is used by the <request> Element (WSE for Microsoft .NET), <response> Element (WSE for Microsoft .NET), and <fault> Element elements to refer to the policy assertion when applying the policy to an endpoint. The value of the Id attribute must be unique to the policy file.
2. Add a <Confidentiality> Element child element to the <Policy> Element (WSE for Microsoft .NET) (1) element.
  The <Confidentiality> Element element defines encryption requirements. The Usage attribute value of "Required" specifies that encryption is required, and additional requirements are specified in child elements.
The following code example defines a policy assertion named policy-c0a22319-6b89-49ff-9b82-bdbac5f04618 and specifies that there are encryption requirements.
```
              <wsp:Policy wsu:Id="policy-c0a22319-6b89-49ff-9b82-bdbac5f04618"
  xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy"
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing">
  <wssp:Confidentiality wsp:Usage="wsp:Required"     xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
```
Specify the token type by adding <KeyInfo> Element (WSE for Microsoft .NET) (1), <SecurityToken> Element, and <TokenType> Element elements.
1. Add a <KeyInfo> Element (WSE for Microsoft .NET) (1) child element to the <Confidentiality> Element element.
2. Add a <SecurityToken> Element child element to the <TokenInfo> Element element.
3. Add a <TokenType> Element child element to the <SecurityToken> Element element and set its value to http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken.
  The <TokenType> Element element specifies the type of security token that must be used to encrypt the message.
The following code example specifies that a UsernameToken security token must be used to encrypt the SOAP message.
```
<wssp:Confidentiality wsp:Usage="wsp:Required"
  xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
  <wssp:KeyInfo>    <wssp:SecurityToken>      <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken</wssp:TokenType>      </wssp:TokenType>
```

Optionally, specify requirements for the token by adding <Claims> Element, <SubjectName> Element, and <UsePassword> Element elements.

Add a <Claims> Element child element to the <SecurityToken> Element element.

Add a <SubjectName> Element child element to the <Claims> Element element.
The value of the <SubjectName> Element element specifies the user name portion of a UsernameToken. The MatchType attribute of the <SubjectName> Element element specifies how to compare the value of the <SubjectName> Element element with the user name portion of a UsernameToken. The following table lists the valid values for the MatchType attribute.

Value	Description
wsse:Exact	The values must be exactly the same, including case.
wsse:Prefix	The value of the <SubjectName> Element element must be a prefix of the Username property.
wsse:Regexp	The value of the <SubjectName> Element element is a regular expression that must match the value of the Username property.

Add a <UsePassword> Element child element to the <Claims> Element element
The Type attribute of the <UsePassword> Element element specifies how the password for a UsernameToken is passed in a SOAP message
The following table lists the possible values for the Type attribute.

Value	Description
wssp:PasswordDigest	The password must be sent hashed. Use PasswordOption.SendHashed when sending the password.
wssp:PasswordText	The password must be sent in clear text. Use PasswordOption.SendPlainText when sending the password.

The following code example specifies that a UsernameToken must be used to encrypt SOAP messages. Furthermore, the UsernameToken must be for the user name someone and the password must be sent hashed.

<wssp:Confidentiality wsp:Usage="wsp:Required"
  xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
  <wssp:KeyInfo>
    <SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">
      <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken</wssp:TokenType>
      <wssp:Claims>        <wssp:SubjectName MatchType="wssp:Exact">          someone</wssp:SubjectName>        <wssp:UsePassword Type="wssp:PasswordDigest"          wsp:Usage="wsp:Required" />       </wssp:Claims>
    </SecurityToken>
  <wssp:KeyInfo>

Map the policy assertion to an endpoint by adding an <endpoint> Element element. Optionally, designate the policy as the default for all SOAP messages by adding the <defaultOperation> Element element.
1. Add an <endpoint> Element element to the <mappings> Element element, and set the uri attribute value to the URI of the application.
  The <endpoint> Element element maps a policy assertion to an endpoint. The uri attribute value specifies the URI of the service to which the policy is mapped.
2. Add a <defaultOperation> Element child element to the <endpoint> Element element.
  The <defaultOperation> Element element specifies the default policy for all operations at the URI specified in the uri attribute.
3. Add <request> Element (WSE for Microsoft .NET), <response> Element (WSE for Microsoft .NET), and <fault> Element child elements to the <defaultOperation> Element element. The value of the policy attribute must match the value of the Id attribute of the <Policy> Element (WSE for Microsoft .NET) (1) element that defines the policy assertion.
The following code example sets the default policy for all SOAP messages sent to the http://www.cohowinery.com/SaleWidgets.asmx endpoint to the policy-c0a22319-6b89-49ff-9b82-bdbac5f04618 policy assertion.
```
<mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
  <endpoint uri="http://www.cohowinery.com/SaleWidgets.asmx">
    <defaultOperation>
      <request policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
      <response policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
      <fault policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
    </defaultOperation>
  </endpoint>
</mappings>
```
Specify the XML elements to be encrypted by adding a <MessageParts> Element for <Confidentiality> Element element to the <Confidentiality> Element element.
1. Add a <MessageParts> Element for <Confidentiality> Element child element to the <Confidentiality> Element element in the policy file for the application, and set the Dialect attribute value to "https://schemas.xmlsoap.org/2002/12/wsse#part".
2. Specify the parts of the message to be encrypted by listing them, separated by spaces, as the value of the <MessageParts> Element for <Confidentiality> Element element.
  When using policy, WSE only supports specifying that the <Body> element must be encrypted.
The following code example specifies that the <Body> element must be encrypted.
```
<wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
  wsp:Body()
</wssp:MessageParts>
```
Add a UsernameToken security token that meets the policy requirements to the PolicyEnforcementSecurityTokenCache of the application where you are sending the SOAP message.

Unlike other security tokens natively supported by WSE, this step is not optional. This is because you cannot specify claims about the UsernameToken (such as the password for the UsernameToken) in policy that are sufficient for WSE to create a new UsernameToken instance.

The following code example adds a UsernameToken to the PolicyEnforcementSecurityTokenCache.
```
PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token )
```
```
PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token );
```

To use code to encrypt a SOAP message by using a user name and password

Open the Web service client project in Visual Studio .NET 2003.
Add references to the Microsoft.Web.Services2,System.Web.Services, and System.Security assemblies.
1. On the Project menu, click Add Reference.
2. Click the .NET tab, select Microsoft.Web.Services2.dll, and then click Select.
3. On the .NET tab, select System.Web.Services.dll, and then click Select.
4. On the .NET tab, select System.Security.dll, and then click Select.
5. Click OK.
Add a Web reference to the Web service that is to receive the SOAP message encrypted with the shared secret.
1. On the Project menu, click Add Web Reference.
2. In the Add Web Reference dialog box, type the URL for the Web service in the Address box, and then click the arrow icon.
3. Verify that the items in the Available references box are the items you want to reference in your project, and then click Add Reference.
Edit the proxy class to derive from the WebServicesClientProtocol.
1. In Solution Explorer, right-click the Reference.cs file for the Web reference just added, and then click View Code.
  
  Note
  
  If the Reference.cs file containing the proxy class is not visible, click Show All Fileson the Solution Explorer toolbar, and then expand the Reference.map node.
2. Change the base class of the proxy class to Microsoft.Web.Services2.WebServicesClientProtocol.
  This modifies the proxy class to emit WS-Addressing and WS-Security SOAP headers when communicating with the Web service. The following code example modifies a proxy class named Service1 to derive from Microsoft.Web.Services2.WebServicesClientProtocol.
```
Public Class Service1
   Inherits Microsoft.Web.Services2.WebServicesClientProtocol
```
```
public class Service1 : 
    Microsoft.Web.Services2.WebServicesClientProtocol {
```
  Note
  
  If you select Update Web Reference in Visual Studio .NET 2003, the proxy class is regenerated, the base class is reset to SoapHttpClientProtocol, and you must repeat this step.
Add Imports or using directives to the top of the file that communicates with the Web service.
1. In Solution Explorer, right-click the file containing the client code, and then click View Code.
2. At the top of the file, add the directives as shown in the following code example.
```
Imports Microsoft.Web.Services2
Imports Microsoft.Web.Services2.Security
Imports Microsoft.Web.Services2.Security.Tokens
```
```
using Microsoft.Web.Services2;
using Microsoft.Web.Services2.Security;
using Microsoft.Web.Services2.Security.Tokens;
```

Edit the method that communicates with the Web service to encrypt the SOAP message by using the UsernameToken.

For more information about encrypting portions of the SOAP message other than the defaults, see How to: Specify the Parts of a SOAP Message That Are Signed or Encrypted.

Create a new UsernameToken instance , specifying the user name, password, and how the password is sent in the SOAP message.
The Web service provides a class that derives from the UsernameTokenManager class, which includes the AuthenticateToken method. The AuthenticateToken method is given the user name in the SOAP message, but no form of the user name's password. The AuthenticateToken method is expected to return the user name's password or password equivalent. WSE calls the AuthenticateToken method, and then compares the password or password equivalent to the one received in the SOAP message. The following table explains the options for passing the password in the SOAP message.

PasswordOption enumeration member	Description
SendNone	The password is never sent in any form in the SOAP message, but WSE does use the password to sign the SOAP message. A recipient would then need to provide a password to WSE during the signature validation stage.
SendHashed	The SHA-1 hash of the password is sent in the SOAP message. This is the best way to help protect the password. When a SOAP message is received with a UsernameToken, WSE calls the AuthenticateToken method of the class deriving from UsernameTokenManager that is registered in the configuration file. The AuthenticateToken method returns a password or password equivalent, which WSE creates a SHA-1 hash from. That SHA-1 hash is compared to the one in the SOAP message and if they are identical, the hashed password is deemed valid.
SendPlainText	The password is always sent in plain text in the SOAP message. This option is recommended only when the UsernameToken is encrypted using a security token or certificate obtained from the target Web service or SSL or a similar protocol is used to connect to the Web service; otherwise, password could be intercepted. WSE running on the recipient's computer compares the plain text password or password equivalent in the SOAP message to the one returned from the AuthenticateToken method of the class deriving from UsernameTokenManager. If they are identical, the password is deemed valid.

The following code example does not send the password in the SOAP request.

UsernameToken userToken = new UsernameToken(userName,password,
                                            PasswordOption.SendNone)

Dim userToken As New UsernameToken(userName, password, _
                                   PasswordOption.SendNone)

Get the SoapContext for the SOAP request that is being made to the Web service.
Service1 is the name of the proxy class for the Web service in the following code example.

Service1 serviceProxy = new Service1();
SoapContext requestContext = serviceProxy.RequestSoapContext;

Dim serviceProxy As New Service1()
Dim requestContext As SoapContext = serviceProxy.RequestSoapContext

Add the UsernameToken to the WS-Security SOAP header.

requestContext.Security.Tokens.Add(userToken);

requestContext.Security.Tokens.Add(userToken)

Encrypt the SOAP message by creating a new instance of the EncryptedData class using the UsernameToken just added to the WS-Security SOAP header.
```
EncryptedData encrypt = new EncryptedData(userToken);
```
```
Dim encrypt As New EncryptedData(userToken)
```
Specify the time-to-live (TTL) for the SOAP message to diminish the chance of someone intercepting the message and replaying it.
The following code example sets the TTL to 1 minute.
```
requestContext.Security.Timestamp.TtlInSeconds = 60;
```
```
requestContext.Security.Timestamp.TtlInSeconds = 60
```

Call the Web service.

serviceProxy.sayHello();

serviceProxy.sayHello()

Example

The following code example is a policy file specifying that all SOAP messages sent to the http://www.cohowinery.com/SaleWidgets.asmx endpoint must have the <Body> element encrypted by a UsernameToken. Furthermore, the UsernameToken must be for the user name someone and the password must be sent hashed.

Note

This code example is designed to demonstrate WSE features and is not intended for production use.

<?xml version="1.0" encoding="utf-8"?>
<policyDocument xmlns="https://schemas.microsoft.com/wse/2003/06/Policy">
  <mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
    <endpoint uri="http://www.cohowinery.com/SaleWidgets.asmx">
      <defaultOperation>
        <request policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
        <response policy="" />
        <fault policy="" />
      </defaultOperation>
    </endpoint>
  </mappings>
  <policies xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsp:Policy wsu:Id="policy-c0a22319-6b89-49ff-9b82-bdbac5f04618"
      xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy"
      xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing" >
      <wssp:Confidentiality wsp:Usage="wsp:Required"
        xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
        <wssp:KeyInfo>
          <SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">
            <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#UsernameToken</wssp:TokenType>
            <wssp:Claims>
              <wssp:SubjectName MatchType="wssp:Exact">
                someone</wssp:SubjectName> 
              <wssp:UsePassword Type="wssp:PasswordDigest"
                wsp:Usage="wsp:Required" />
            </wssp:Claims>
          </SecurityToken>
        </wssp:KeyInfo>
        <wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
          wsp:Body() 
        </wssp:MessageParts>
      </wssp:Confidentiality>
    </wsp:Policy>
  </policies>
</policyDocument>

The following code example creates a UsernameToken security token, and then encrypts a SOAP request by using the token.

Try
    Dim userToken As New UsernameToken(userName, password, _
        PasswordOption.SendNone)
    Dim svc As New Proxy.Service1() 
    Dim requestContext As SoapContext = svc.RequestSoapContext
   
    ' Set the TTL to one minute.
    requestContext.Security.Timestamp.TtlInSeconds = 60
   
    ' Add the security token. 
    requestContext.Security.Tokens.Add(userToken )
' Encrypt the SOAP request by using a user name and password.
    requestContext.Security.Elements.Add(new EncryptedData(userToken ))

    MessageBox.Show( svc.sayHello() )
Catch ex As Exception
    MessageBox.Show( ex.ToString() )
End Try

try 
{
UsernameToken userToken = new UsernameToken(userName,password,
    PasswordOption.SendNone)

    Proxy.Service1 svc = new Proxy.Service1();
        SoapContext requestContext = svc.RequestSoapContext;

    // Set the TTL to one minute.
    requestContext.Security.Timestamp.TtlInSeconds = 60;
    
    // Encrypt the SOAP request by using a user name and password.
    requestContext.Security.Elements.Add(
        new EncryptedData(userToken ));

    MessageBox.Show( svc.sayHello() );
}
catch (Exception ex) 
{
    MessageBox.Show( ex.ToString() );
}

How to: Encrypt a SOAP Message by Using a User Name and Password

To use policy to encrypt a SOAP message by using a user name and password

To use code to encrypt a SOAP message by using a user name and password

Example

See Also

Tasks

Reference

Additional resources