PortSight Secure Access Documentation

Managing X.509 Certificates

 

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:

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 :

  1. Click Start -> Run, type mmc, and then click OK.
  2. In the File menu, click Add/Remove Snap-in, and then click Add.
  3. Under Snap-in, double-click Certificates.
  4. Click My user account and then click Finish.
  5. This snap-in allows you to manage certificates for the current user.
  6. "Certificates - Current User" appears in the list of selected snap-ins for the new console.
  7. Repeat step 3.
  8. Click Computer account, click Next, click Local computer, and then click Finish.
  9. This snap-in allows you to manage local computer certificates.
  10. Click Close.
  11. Click OK.
  12. 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

 

 

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: