How to: Encrypt a SOAP Message

  • Article

WSE allows you to encrypt your SOAP messages by writing code or allowing an administrator to set the encryption requirements using policy.

The procedure that encrypts a SOAP message using user code outlines just the steps to encrypt the SOAP message and does not include the steps it takes to obtain a specific security token or send the SOAP message. For step-by-step procedures for the specific type of security token you are using, see Supported Security Tokens.

To use policy to encrypt a SOAP message

  1. 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 (WSE for Microsoft .NET) (1) element. The Id attribute value provides a name that is used by <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.
    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">

  2. 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 URI for the specific security token.
      The <TokenType> Element element specifies the type of security token that must be used to encrypt the SOAP message.

    The following code example specifies that a KerberosToken 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>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST</wssp:TokenType>

  3. 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>

  4. 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>

  5. Optionally, add a security token that meets the policy requirements to the PolicyEnforcementSecurityTokenCache of the application where you are sending the SOAP message.

    This step is optional because WSE looks in the following caches in the specified order to find a security token that matches the policy:

    1. The Tokens collection of the SoapContext associated with the SOAP message.
    2. The PolicyEnforcementSecurityTokenCache token cache.

    WSE uses the first security token that it finds that matches the policy.

    The following code example adds a security token to the PolicyEnforcementSecurityTokenCache.

    PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token )

    PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token );

To write code to encrypt a SOAP message

  1. Obtain the security token that you want to encrypt the SOAP message with.

    The following code example calls a GetSecurityToken method to get an X509SecurityToken.

    Dim encryptionToken As X509SecurityToken = GetSecurityToken()

    X509SecurityToken encryptionToken = GetSecurityToken();

  2. Get the SoapContext for the SOAP message.

    The following code example gets the SoapContext for a SOAP request, where Service1 is the name of the proxy class to the Web service.

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

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

  3. Create a new instance of the EncryptedData class using the security token you want to encrypt the SOAP message with.

    Note

    The security token does not need to be added to the SOAP message.

    Dim enc As New EncryptedData(encryptionToken)

    EncryptedData enc = new EncryptedData(encryptionToken);

  4. Add the EncryptedData to the WS-Security SOAP header.

    requestContext.Security.Elements.Add(enc)

    requestContext.Security.Elements.Add(enc);

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 encrypt the <Body> element by using a Kerberos service ticket issued from the COHOWINERY realm for communication between the current user and the computer named computer1@cohowinery.com.

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="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
        <fault policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
      </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>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST</wssp:TokenType>
            <wssp:TokenIssuer>COHOWINERY</wssp:TokenIssuer>
            <wssp:Claims>
              <wssp:ServiceName>host/computer1@cohowinery.com</wssp:ServiceName>
            </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 KerberosToken security token, and then encrypts a SOAP request by using the token.

Try
    Dim kerbToken As New KerberosToken( "host/" + hostname + _
      "@" + domainName)
    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(kerbToken)
    ' Encrypt the SOAP request by using the Kerberos ticket.
    requestContext.Security.Elements.Add(new EncryptedData(kerbToken))

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

try 
{
    KerberosToken kerbToken = new KerberosToken( "host/" + hostname + _
      "@" + domainName);                

    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 the Kerberos ticket.
    requestContext.Security.Elements.Add(new
        EncryptedData(kerbToken));

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

See Also

Reference

<Confidentiality> Element
EncryptedData

Concepts

Encrypting a SOAP Message