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

  • Article

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.

    For Web services hosted by ASP.NET, the account that the ASP.NET worker process runs under is controlled by the <processModel> element in the Machine.config file, unless the Web service is running under Internet Information Services (IIS) version 6.0. Set the userName attribute of the <processModel> element to specify the account ASP.NET runs under. By default, the userName attribute is set to the special Machine account, which maps to the low-privileged ASPNET user account created when the .NET Framework SDK is installed. IIS 6 uses application pools to determine the process identity, and the default account a Web service runs under is Network Service. Therefore, for a Web service running under IIS 6, the default user account is Network Service; otherwise the default is the ASPNET user account.

For more information, see Managing X.509 Certificates.

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

  1. In the Web.config file for the Web application that is hosting the Web service, include an <soapServerProtocolFactory> Element element in the <webServices> 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 <soapServerProtocolFactory> Element element must be on one line, even though the following sample shows it split across multiple lines for readability.

    <configuration>
   <system.web>
        <webServices>
            <soapServerProtocolFactory type="Microsoft.Web.Services3.WseProtocolFactory, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" /> 
        </webServices>
    </system.web>
   </system.web>
</configuration>

  2. Apply a policy to the Web service that requires SOAP messages to be encrypted by an X.509 certificate.

    1. Add a policy to the Web service's policy file that requires SOAP messages to be encrypted using an X.509 certificate.
      The <anonymousForCertificateSecurity> Element, <mutualCertificate10Security> Element, <mutualCertificate11Security> Element, and <usernameForCertificateSecurity> Element turnkey assertions require that SOAP requests are encrypted by a EncryptedKeyToken security token that is based on an X.509 certificate.

      Note

      When a policy is not explicitly specified for a Web service that is WSE-enabled, SOAP messages are processed using a pipeline that follows the semantics of the WSE 2.0 pipeline. The WSE 2.0 pipeline attempts to decrypt SOAP messages that are encrypted by an X.509 certificate.

      The following code example demonstrates how to secure a SOAP message exchange using an X509SecurityToken security token for protection and a UsernameToken security token for client authentication. The code example defines a policy assertion named ClientPolicy that specifies that a X509SecurityToken security token is used to digitally sign the SOAP message, and to encrypt the <body> element of the SOAP message. The keys used to generate the digital signature and encrypt the <body> element are not the same keys, but rather are derived from the same key. In the following code example, the user name and password needs to be added in code.

      <policies>
  <extensions>
    <extension name="usernameForCertificateSecurity" type="Microsoft.Web.Services3.Design.UsernameForCertificateAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="x509" type="Microsoft.Web.Services3.Design.X509TokenProvider, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="requireActionHeader"
               type="Microsoft.Web.Services3.Design.RequireActionHeaderAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </extensions>
  <policy name="ServicePolicy">
    <usernameForCertificateSecurity 
      establishSecurityContext="false" 
      renewExpiredSecurityContext="true" 
      requireSignatureConfirmation="false" 
      MessageProtectionOrder="SignBeforeEncrypt" 
      requireDerivedKeys="true" >
      <serviceToken>
        <x509
          storeLocation="LocalMachine"
          storeName="My"
          findValue="CN=WSE2QuickStartServer"
          findType="FindBySubjectDistinguishedName" />
      </serviceToken>
      <protection>
        <request
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <response 
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="true" />
        <fault
          signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
          encryptBody="false" />
      </protection>
    </usernameForCertificateSecurity>
    <requireActionHeader />
  </policy>
</policies>

    2. Apply a PolicyAttribute attribute to the Web service.
      The PolicyAttribute attribute can be applied to the class that is implementing the Web service methods. This applies the policy to all Web service methods (operations) within that class.
      The following code example specifies that all Web service methods within the Service class adhere to the ServicePolicy policy.

      <WebService(Namespace:="https://www.contoso.com/")> _
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _
<Policy("ServicePolicy")> _
Public Class Service
    Inherits System.Web.Services.WebService

      [WebService(Namespace = "https://www.contoso.com/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[Policy("ServicePolicy")] 
public class Service : System.Web.Services.WebService
{

See Also

Tasks

How to: Encrypt a SOAP Message Using an X.509 Certificate

Concepts

Encrypting a SOAP Message

Other Resources

Managing X.509 Certificates
Brokered Authentication - X.509 PKI
X.509 Technical Supplement