How to: Make X.509 Certificates Accessible to WSE

  • Article

In order for an X.509 certificate to be accessible to WSE, WSE must know the certificate store to obtain the certificate store from and have access to the file containing the private key associated with the X.509 certificate in certain circumstances.

Developers can choose programmatically the certificate store that is used to digitally sign or encrypt SOAP messages by using X.509 certificates. However, when WSE receives a SOAP message that has been signed or encrypted using an X.509 certificate, WSE decides which certificate store to use.

In order for WSE to obtain the private key associated with an X.509 certificate from the local computer certificate store, it must have permission to do so. By default, only the owner and the System account can access the private key of a certificate. Also by default, the ASP.NET service runs under the ASPNET account, and that account does not have access to the private key.

To make X.509 certificates accessible to WSE

  1. Specify the certificate store that WSE uses to obtain X.509 certificates by adding an <x509> Element element to the configuration file for the application.

    The following table details the default location where WSE looks for X.509 certificates.

    X.509 certificate use Client Application Web service (.ASMX)

    Signing or encrypting an outgoing SOAP message.

    Local Computer's Personal Store

    Local Computer's Personal Store

    Verifying the signature of an incoming SOAP message.

    SOAP message

    SOAP message

    Decrypting an inbound SOAP message.

    Local Computer's Personal Store

    Local Computer's Personal Store

    Note

    An outgoing SOAP message can be a SOAP request sent from a client application or a SOAP response sent from a Web service. Likewise, an incoming SOAP message can be a SOAP request received by a Web service or a SOAP response received by a client application.

    When added to the configuration file for an application, the following code example specifies that WSE retrieves X.509 certificates from the CurrentUser certificate store.

    <configuration>
  <microsoft.web.services2>
    <security>
      <x509 storeLocation="CurrentUser" />
    </security>
  </microsoft.web.services2>
</configuration>

  2. Give the account under which WSE is running read access to the file containing the private key associated with the X.509 certificate.

    The following table details whether a private key must be available when using an X.509 certificate.

    X.509 certificate use Private key

    Digitally signing an outbound SOAP message

    Yes

    Verifying the signature of an inbound SOAP message

    No

    Encrypting an outbound SOAP message

    No

    Decrypting an inbound SOAP message

    Yes

    For client applications and applications using SOAP messaging, the account under which WSE is running is the currently logged in user.

    For Web services created using ASP.NET, the account 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.

    1. Open the X.509 Certificate Tool (WseCertificate2.exe).
    2. Set the certificate location and store name where the certificate is located.
    3. Click Select the certificate from the store, choose the certificate you want to set the permissions for, and then click OK.
    4. Click Open Private Key File Properties, click the Security tab, add the ASPNET or Network Service account, depending on which version of IIS the Web service is running under, and then select the Read option.

    Note

    When you move or copy an X.509 certificate from one certificate store to another, do not use the Copy or Cut command in Microsoft Management Console (MMC) Certificates snap-in. Instead, use the Certificates snap-in to export the certificate from one certificate store and then import the certificate into the destination certificate store.When you copy or cut a certificate from a certificate store and then paste it into another, WSE will not have sufficient permissions to the file. The MMC does not move the file associated with the X.509 certificate. So, even if you grant read permissions on the file to the account under which WSE is running, that account may not have access to the path to the file. To avoid this issue, export the file from one certificate store and import it into the other.

See Also

Tasks

How to: Obtain an X.509 Certificate
How to: Use the X.509 Certificate Management Tools
How to: Specify the Certificate Authority Certificate Chain Used to Verify Signatures
X.509 Certificate Tool (WseCertificate2.exe)

Other Resources

X.509 Certificate
Managing X.509 Certificates