How to: Decrypt a SOAP Message Encrypted Using a Kerberos Ticket

Article
09/15/2006

Decrypting a SOAP message that was encrypted using a Kerberos service ticket requires only a configuration setting.

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

The following procedure can be used with both the KerberosToken and KerberosToken2 security tokens. To use the procedure for KerberosToken2 security tokens, do the following:

In code examples, replace KerberosToken with KerberosToken2.
In policy examples, change the value of the <TokenType> Element element from https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST to https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5_AP_REQ.

For more details about the difference between the KerberosToken and KerberosToken2 security tokens, see Differences between KerberosToken and KerberosToken2.

To decrypt SOAP messages encrypted using a Kerberos service ticket

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> section must be on one line, even though the following sample 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 Kerberos ticket

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/2003/12/kerberos/Kerberosv5ST.
  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>
```
Optionally, specify requirements about 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 domain, also known as the Kerberos realm, which issued the Kerberos ticket. WSE does not support Kerberos delegation, so this must be the same realm the recipient is a member of.
  
  Note
  
  The value of the <TokenIssuer> Element (WSE for Microsoft .NET) (1) must be in uppercase.
  
  The following code example specifies that a Kerberos service ticket must be used to encrypt SOAP messages. Furthermore, the Kerberos service ticket must be obtained from a KDC in the COHOWINERY realm.
```
                  <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>
      </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> 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.
  When using policy, WSE only supports specifying the <Body> element must be encrypted.
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 specifying that all SOAP messages sent to the http://www.cohowinery.com/SaleWidgets.asmx endpoint have the <Body> element encrypted by a Kerberos service ticket issued from the COHOWINERY realm.

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>
          </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 Kerberos Ticket

To decrypt SOAP messages encrypted using a Kerberos service ticket

To use policy to require incoming SOAP messages to be encrypted by a Kerberos ticket

Example

See Also

Tasks

Reference

Other Resources

Additional resources