How to: Decrypt a SOAP Message Encrypted Using a Security Context Token

Article
09/15/2006

Decrypting a SOAP message that was encrypted using a security context token requires only a configuration setting and, in some cases, that a decryption key is accessible.

You can also require that the SOAP message be encrypted using policy.

To decrypt SOAP messages encrypted using a security context token

In the Web.config file for the Web service, include an <add> Element for <soapExtensionTypes> (WSE for Microsoft .NET) element in the <soapExtensionTypes> section.

When the SOAP message recipient is a Web service client, this configuration entry is not required. Instead, the base class that the proxy class derives from must be changed to derive from the WebServicesClientProtocol.

The following code example shows the configuration entry that must be placed in the Web.config file for WSE to run with a Web service. The type attribute of the <add> Element for <soapExtensionTypes> (WSE for Microsoft .NET) element in the <soapExtensionTypes> section must be on one line, even though the following example shows it split across multiple lines for readability.
```
<configuration>
  <system.web>
    <webServices>
      <soapExtensionTypes>
        <add type="Microsoft.Web.Services2.WebServicesExtension, 
          Microsoft.Web.Services2,Version=2.0.0.0, Culture=neutral, 
          PublicKeyToken=31bf3856ad364e35" 
          priority="1" group="0"/>
      </soapExtensionTypes>
    </webServices>
  </system.web>
</configuration> 
```

To use policy to require incoming SOAP messages to be encrypted by a security context token

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 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.
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 https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct.
  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 SecurityContextToken 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/2004/04/security/sc/sct</wssp:TokenType>
```
Specify the security token service that issued the token by adding a <TokenIssuer> Element (WSE for Microsoft .NET) (1) element.
- Add a <TokenIssuer> Element (WSE for Microsoft .NET) (1) child element to the <SecurityToken> Element element.
  The <TokenIssuer> Element (WSE for Microsoft .NET) (1) element specifies the security token service that issued the SecurityContextToken security token.
The following code example specifies that the http://www.cohowinery.com/secureConversation.ashx security token service issued the SecurityContextToken security token.
```
<wssp:SecurityToken>
  <wssp:TokenIssuer>    http://www.cohowinery.com/secureConversation.ashx  </wssp:TokenIssuer>
```
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 child element to the <mappings> Element element in the policy file for the application, 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 application's default policy for all SOAP messages to the policy-c0a22319-6b89-49ff-9b82-bdbac5f04618 policy assertion.
```
<mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
  <endpoint uri="https://localhost/SecureConvPolicyService/SecureConvService.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 Default attribute value to "https://schemas.xmlsoap.org/2002/12/wsse#part".
  The <MessageParts> Element for <Confidentiality> Element element specifies the XML elements that must be encrypted. The Dialect attribute specifies the expression dialect used to specify the parts of the SOAP message. The only dialect supported by WSE is "https://schemas.xmlsoap.org/2002/12/wsse#part".
2. Specify the parts of the message to be encrypted as the value of the <MessageParts> Element for <Confidentiality> Element element.
  For encryption requirements, the only element that may be specified using policy is the <Body> element.
The following code example specifies that the <Body> element is encrypted.
```
<wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
  wsp:Body()
</wssp:MessageParts>
```

Example

The following code example is a policy file for a target Web service that issues SecurityContextToken security tokens. The policy requires that security token requests sent to the https://www.contoso.com/SecureConvService.asmx endpoint include a base token that is a UsernameToken security token. SOAP requests sent to the Web service must be signed and encrypted using the issued SecurityContextToken security token.

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>
    <endpoint uri="https://www.contoso.com/SecureConvService.asmx">
      <operation
        requestAction="http://stockservice.contoso.com/StockQuoteRequest">
        <!-- Requests must encrypted with an SCT -->
        <request policy="#EncryptWithSCT" />
        <response policy="" />
        <!-- No policy for faults -->
        <fault policy="" />
      </operation>
            
      <!--
        The following section describes the policy requirements for the
        SCT issuing service. The built in SecurityContextTokenManager
        will send requests to an SCT's token issuer as described in policy
        and the following policy mapping demonstrates how to use policy
        make sure the requests get signed with an appropriate base token.
      -->
      <operation
        requestAction="https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/SCT">
        <request policy="#SignWithUsernameToken" />
        <response policy="" />
        <fault policy="" />
      </operation>
    </endpoint>
        
  </mappings>
  <policies 
    xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing"
    xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy"
    xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy"
    xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd"
    xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext"
    xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
        
    <!--
      This policy is used for the target Web service. It requires 
      the body to be encrypted with a SecureContextToken token.
    -->
    <wsp:Policy wsu:Id="EncryptWithSCT">
      <!-- 
        MessagePredicate is used to require the headers.
        This assertion should be used along with the 
        Integrity assertion when the presence of the 
        signed element is required.
        
        NOTE: this assertion doesn't do anything for 
        enforcement (send-side) policy.
      -->
      <wsp:MessagePredicate 
        Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
        wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wse:Timestamp()
       </wsp:MessagePredicate>

       <!-- 
         Confidentiality is used to require that the body be encrypted
         with the SCT.
       -->
       <wssp:Confidentiality wsp:Usage="wsp:Required">
         <wssp:KeyInfo>
           <wssp:SecurityToken wse:IdentityToken="true">
             <wssp:TokenType>https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk</wssp:TokenType>
             <wssp:Claims>
               <wse:Parent>
                 <wssp:SecurityToken wse:IdentityToken="true">
                   <wssp:TokenType>https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct</wssp:TokenType>
                  <wssp:Claims>
                    <wse:BaseToken>
                      <wssp: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:SecurityToken>
                    </wse:BaseToken>
                  </wssp:Claims>                        
                </wssp:SecurityToken>
              </wse:Parent>
            </wssp:Claims>                        
          </wssp:SecurityToken>
        </wssp:KeyInfo>
        <wssp:MessageParts
          Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
          wsp:Body()
        </wssp:MessageParts>
      </wssp:Confidentiality>
    </wsp:Policy>
        
    <!--
      This policy is used for the token issuer service. It requires 
      the body and addressing headers to be signed with a 
      UsernameToken.    
    -->
    <wsp:Policy wsu:Id="SignWithUsernameToken">

    <!-- 
      MessagePredicate is used to require the headers.
      This assertion should be used along with the 
      Integrity assertion when the presence of the 
      signed element is required.
       
      NOTE: this assertion doesn't do anything for 
      enforcement (send-side) policy.
    -->
      <wsp:MessagePredicate
        Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
        wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wse:Timestamp()
      </wsp:MessagePredicate>

      <!-- 
        Integrity is used to require the headers to be signed 
        Note that a only an authenticated username token is 
        required. Many Web services will also use the token 
        for authorization, such as by using the <wse:Role>
        claim.
      -->
      <wssp:Integrity wsp:Usage="wsp:Required">
        <wssp:TokenInfo>
          <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>
          </SecurityToken>
        </wssp:TokenInfo>
        <wssp:MessageParts
          Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
          wse:Timestamp() wse:Addressing() wsp:Body()
        </wssp:MessageParts>
      </wssp:Integrity>
    </wsp:Policy>
  </policies>
</policyDocument>

<?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="https://localhost/SecureConvPolicyService/SecureConvService.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>          <!-- The SecurityToken element describes the requirements            for the certificate that must be used for encryption. -->          <SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">            <wssp:TokenType>https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct</wssp:TokenType>            <wssp:TokenIssuer>              https://localhost/SecureConvPolicyService/secureConversation.ashx            </wssp:TokenIssuer>          </SecurityToken>        </wssp:KeyInfo>        <wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">            wsp:Body()        </wssp:MessageParts>      </wssp:Confidentiality>
    </wsp:Policy>
  </policies>
</policyDocument>

How to: Decrypt a SOAP Message Encrypted Using a Security Context Token

To decrypt SOAP messages encrypted using a security context token

To use policy to require incoming SOAP messages to be encrypted by a security context token

Example

See Also

Tasks

Reference

Other Resources

Additional resources