This topic describes how to configure X.509 certificates so that they can be used by WSE applications.

Obtaining an X.509 Certificate

In order to use any of the features of the WSE that use X.509 certificates, certificates must first be obtained.

You have the following options how to obtain an X.509 certificate:

Purchase a certificate from a Certificate Authority, such as VeriSign, Inc.
Set up your own certificate service and have a certificate authority sign the certificates. Windows 2000 Server, Windows 2000 Advanced Server, and Windows 2000 Datacenter Server all include Certificate Services that support public key infrastructure (PKI). See Set up your own certificate service.
Set up your own certificate service and not have the certificates signed. See Set up your own certificate service.

Whichever approach you take, the recipient of the SOAP request containing the X.509 certificate must trust the X.509 certificate. This means that the X.509 certificate or an issuer in the certificate chain is in the Trusted People certificate store and that the X.509 certificate is not in the Untrusted Certificates store.

It is not critical what intended purpose you specify while requesting the certificate, but it is essential to choose the "Use local machine store" property. You must be an administrator to generate key in the local machine store.

Managing X.509 Certificates

Once you have one or more X.509 certificates, use the Microsoft Management Console (MMC) Certificates snap-in to manage them.

To manage X.509 certificates :

Click Start -> Run, type mmc, and then click OK.
In the File menu, click Add/Remove Snap-in, and then click Add.
Under Snap-in, double-click Certificates.
Click My user account and then click Finish.
This snap-in allows you to manage certificates for the current user.
"Certificates - Current User" appears in the list of selected snap-ins for the new console.
Repeat step 3.
Click Computer account, click Next, click Local computer, and then click Finish.
This snap-in allows you to manage local computer certificates.
Click Close.
Click OK.
Click Save in the File menu to save this console.

How the WSE Finds an X.509 Certificate

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

The following table details where the WSE looks for X.509 certificates when a SOAP message is received:

X.509 certificate use	Client application or XML Web service
Verifying the signature of an inbound SOAP message	SOAP message
Decrypting an inbound SOAP message	Local machine*

* This is configurable using the <x509> configuration setting.

Note: An outbound SOAP message can be a SOAP request sent from a client application or a SOAP response sent from an XML Web service. Likewise, an inbound SOAP message can be a SOAP request received by an XML Web service or a SOAP response received by a client application.

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

Required Permissions for the WSE to Sign or Decrypt with an X.509 Certificate

WSE must have permission to obtain the X.509 private key from the local computer certificate store. 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.

Important Note

Give the account under which ASP.NET is running (ASPNET by default) Full Control access to the files containing the keys in the following folder:

C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys

		Important Note
Give the account under which ASP.NET is running (ASPNET by default) Full Control access to the files containing the keys in the following folder: C:\Documents and Settings\All Users\Application Data\Microsoft\Crypto\RSA\MachineKeys

Note: Determining which key file in the MachineKeys folder is associated with a certificate can be difficult. One method is to note the creation date and time when creating a new certificate. When viewing the files in the MachineKeys directory, check the Date Modified field for the corresponding date and time.

Specifying the CA Certificate Chain Used to Verify Signatures

When the WSE receives a SOAP message signed using an X.509 certificate, by default, it verifies that the X.509 certificate was issued by a trusted certificate authority (CA). It looks up in the certificate store and determines if the certificate of the certificate authority has been designated as trusted. The CA certificate chain must be installed in the correct certificate store so that the client or server trust the certificate issued by this authority.

Please follow these steps to install a CA certificate chain on both client and server:

For each certificate authority a SOAP message recipient intends to trust X.509 certificates issued from, install the CA certificate chain into the certificate store the WSE is configured to retrieve X.509 certificates from.

For instance, if a SOAP message recipient intends to trust X.509 certificates issued by Microsoft, the CA certificate chain for Microsoft must be installed in the certificate store the WSE is set up to look for X.509 certificates from. The certificate store the WSE looks in is controlled by the <x509> configuration element. Microsoft Windows does ship with a set of default certificate chains for trusted certificate authorities, so you may not need to install the certificate chain for all certificate authorities.
1. Export the CA certificate chain.
  
  Exactly how this is done will depend on the certificate authority, but if the certificate authority is running Microsoft Certificate Services, select the option to Download a CA certificate, certificate chain, or CRL. Next choose the "Download CA certificate" chain link.
2. Import the CA certificate chain.
  
  Open the Certificates snap-in with Microsoft Management Console. Select the Trusted Root Certification Authorities folder for the certificate store the WSE is configured to retrieve X.509 certificates from. Then right-click the Certificates folder contained in the Trusted Root Certification Authorities, point to All Tasks, and then click Import. Provide the file exported in Step a. For details about configuring which certificate store the WSE is configured to retrieve X.509 certificates from, see <x509>.