How to: Decrypt a SOAP Message Encrypted with an X.509 Certificate

Article
09/15/2006

To decrypt a SOAP message encrypted with an X.509 certificate, the Web Services Enhancements for Microsoft .NET (WSE) must be configured to process the SOAP message and the recipient must have access to the X.509 certificate and the private key that encrypted the SOAP message.

The recipient of a SOAP message is not always a Web service. For example, when a Web service encrypts a SOAP response, the Web service client is the recipient. It is common for a Web service to encrypt the SOAP response by using the X.509 certificate that the client used to sign the SOAP message. To do so, the Web service retrieves the X.509 certificate with its public key from the SOAP message and passes that to a new instance of the EncryptedData class. Then the Web service client just needs access to its own X.509 certificate and its private key.

To give the recipient access to the X.509 certificate that encrypted the SOAP message

If the X.509 certificate is stored in the local machine store, when the X.509 certificate is obtained for the server, select the Use local machine store option, and then follow the steps to install the certificate.
For a Web service, it is easiest to place the X.509 certificate in the local machine store. A Web service runs under the process identity for ASP.NET. By default, this is an auto-generated user account named ASPNET, which is created when ASP.NET is set up, so you do not have access to the password for that account. Because of this, adding the X.509 certificate to the current user account is difficult. You can change the account that ASP.NET runs under by changing the <processModel> element in the Machine.config file. If you do change the account that ASP.NET runs under, give the new ASP.NET account the minimum level of permissions required for ASP.NET.

For more information, see Managing X.509 Certificates.

To decrypt a SOAP message encrypted with an X.509 certificate

In the Web.config file for the Web application that is hosting 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 the WebServicesClientProtocol class.

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 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 are encrypted by an X.509 certificate

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.

Use the <Policy> Element (WSE for Microsoft .NET) (1) element to define criteria that a SOAP message must meet. The criteria are specified as child elements of the <Policy> element. The Id attribute is used to name the policy assertion, which is used by the <request> Element (WSE for Microsoft .NET), <response> Element (WSE for Microsoft .NET), and <fault> Element elements to refer to a policy assertion when applying the policy to an endpoint.

The following code example defines a policy assertion named policy-c0a22319-6b89-49ff-9b82-bdbac5f04618.
```
<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" >
```
Add a <Confidentiality> Element child element to the <Policy> Element (WSE for Microsoft .NET) (1) element.

Use the <Confidentiality> Element element to define encryption requirements. The requirements are specified in child elements.

The following code example specifies that there are encryption requirements.
```
<wsp:Policy wsu:Id="policy-08b0e1ca-9428-44fd-93f4-b11de6fa08e0"
  xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy">
  <wssp:Confidentiality wsp:Usage="wsp:Required"    xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
```
Add a <KeyInfo> Element (WSE for Microsoft .NET) (1) child element to the <Confidentiality> Element element.

Use the <KeyInfo> Element (WSE for Microsoft .NET) (1) element to define requirements for security tokens used to encrypt SOAP messages.

The following code example specifies that there are requirements on security tokens used to encrypt SOAP messages.
```
              <wssp:Confidentiality wsp:Usage="wsp:Required"
                xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
                <wssp:KeyInfo>
```
Add a <SecurityToken> Element child element to the <KeyInfo> Element (WSE for Microsoft .NET) (1) element.

Use the <SecurityToken> Element element to define requirements on security tokens used to encrypt SOAP messages.

The following code example specifies that there are requirements on security tokens used to encrypt SOAP messages.
```
<wssp:KeyInfo>
  <wssp:SecurityToken>
```
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-x509-token-profile-1.0#X509v3.

Use the <TokenType> Element element to specify the type of security token that must be used to encrypt SOAP messages.

The following code example specifies that an X509SecurityToken must be used to encrypt the SOAP messages.
```
<wssp:SecurityToken>
  <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</wssp:TokenType>
```
Optionally, add a <Claims> Element child element to the <SecurityToken> Element element.

Use the <Claims> Element element to specify requirements specific to an X.509 certificate. The requirements are specified in the <Role> Element or <SubjectName> Element child elements.

The following code example specifies that there are specific requirements on the X.509 certificate used to encrypt SOAP messages.
```
<wssp:SecurityToken>
  <wssp:Claims>
```
Optionally, add a <SubjectName> Element child element to the <Claims> Element element.

Use the <SubjectName> Element element to specify that the SOAP message must be encrypted using an X.509 certificate with a specific subject name.

Note

When the <SubjectName> element is used to specify the subject name for an X.509 certificate, the value of the element is formatted differently than what appears in the MMC. The value that must be placed in the <SubjectName> element maps to the Subject field that appears on the Details tab of the Certificates snap-in within the MMC. If you copy the value of the Subject field from the MMC, the value has to be reversed prior to placement in the <SubjectName> element. For example, if the value of the Subject field is CN=WSE2QuickStartServer, O=Coho Winery, L=Woodinville, S=WA, C=US, the value that must be added to the <SubjectName> element is C=US, S=WA, L=Woodinville, O=Contoso, CN=Coho Winery.

The following code example specifies that the SOAP message must have been encrypted using the X.509 certificate with a subject name of CN=WSE2QuickStartClient.
```
<wssp:Claims>
  <wssp:SubjectName>CN=WSE2QuickStartClient</wssp:SubjectName>
```
Optionally, add a <TokenIssuer> Element (WSE for Microsoft .NET) (1) child element to the <SecurityToken> Element element.

Use the <TokenIssuer> Element (WSE for Microsoft .NET) (1) element to specify the certification authority that issued the X.509 certificate.

Note

The value of the <TokenIssuer> element is formatted differently than what appears in the MMC. The value that must be placed in the <TokenIssuer> element maps to the Issuer field that appears on the Details tab of the Certificates snap-in within the MMC. If you copy the value of the Issuer field from the MMC, the value has to be reversed prior to placement in the <TokenIssuer> element. For example, if the value of the Issuer field is CN=CertServer DC=corp DC=contoso DC=com, the value that must be added to the <TokenIssuer> element is DC=com DC=contoso DC=corp CN=CertServer.

The following code example specifies that the X.509 certificate that was used to encrypt SOAP messages must have been issued by the DC=com DC=contoso DC=corp CN=CertServer certification authority.
```
<wssp:SecurityToken>
  <wssp:TokenIssuer>DC=com DC=contoso DC=corp CN=CertServer</wssp:TokenIssuer>
```
Add a <MessageParts> Element for <Confidentiality> Element element to the <Confidentiality> Element element.

Use the <MessageParts> element to specify the XML elements that 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>
```

Add an <endpoint> Element element to the <mappings> Element element.

Use the <endpoint> Element element to apply a policy assertion to an endpoint.

The following code example sets the 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/X509SignPolicyService/X509SigningService.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>

Example

The following code example is a policy file specifying that all SOAP messages sent to the http://www.cohowinery.com/Service1.asmx endpoint must be encrypted using an X.509 certificate.

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/Service1.asmx">
      <defaultOperation>
        <request policy="#policy-08b0e1ca-9428-44fd-93f4-b11de6fa08e0" />
        <response policy="#policy-08b0e1ca-9428-44fd-93f4-b11de6fa08e0" />
        <fault policy="#policy-08b0e1ca-9428-44fd-93f4-b11de6fa08e0" />
      </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-08b0e1ca-9428-44fd-93f4-b11de6fa08e0" xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy">
      <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-x509-token-profile-1.0#X509v3</wssp:TokenType>
          </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 with an X.509 Certificate

To give the recipient access to the X.509 certificate that encrypted the SOAP message

To decrypt a SOAP message encrypted with an X.509 certificate

To use Policy to require incoming SOAP messages are encrypted by an X.509 certificate

Example

See Also

Tasks

Concepts

Other Resources

Additional resources