Setting up .NET SOAP clients that use SSL client certificates

The following describes how to write a C# client in Visual Studio 2010, which performs an SSL handshake involving an SSL client certificate (client verification).

Ensure that you have privileged access as they are required by several steps!

Step 1: Creating, configuring, and deploying the required certificate files

For this step, you will need to create the following files:

• CA certificate
• Client certificate
• Client certificate signing request (CSR)

Create a secure directory to which only root has read/write access. This is to limit access to the certificate files to all but the root user.

The common name (CN) of the CA and the client certificates must be different. If they are the same, you will get a naming collision and this will cause problems in later steps.

To create the required certificate files

1. From a Command Prompt window, change to your secure, root-only working directory.

2. Build the certification authority (CA) key using the following commands:

   openssl genrsa ‑des3 ‑out client‑ca.key 4096

   openssl req ‑new ‑x509 ‑days 365 ‑key client‑ca.key ‑out client‑ca.crt

   When prompted, provide the common name (CN), organization (O), and organizational unit (OU) for both CA and server. If you do not have a fully qualified domain name, use the IP address you will be using to access your SSL site for common name (CN).

3. Create the client certificate CSR using the following commands:

   openssl genrsa ‑des3 ‑out client.key 4096

   openssl req ‑new ‑key client.key ‑out client.csr

   The common name used for the CSR file in the aforementioned command should match the DNS name or IP address of your client. If they don't match, the server may reject the certificate.

   At this point, you should have the following files:

   • client.csr. Client certificate CSR.
   • client-ca.crt. CA certificate.
   • client.crt. Client certificate.

4. Sign the client certificate (client.crt) with the CA certificate (client-ca.crt) using the following command:

   openssl x509 ‑req ‑days 365 ‑in client.csr ‑CA client‑ca.crt ‑CAkey client‑ca.key ‑set_serial 01 ‑out client.crt

   This command has the following effects:

   • It takes your signing request (client.csr) and creates a one-year valid signed client certificate (client.crt). You will need to repeat this process after a year (365 days).
   • It tells the CSR which certification authority to use (client-ca.crt), which CA key to use, and which server key to sign.
   • It sets the serial number to 01. If you repeat this process after using this client certificate, use 02, and 03 for the next one, and so on.
   • It saves the signed key in the file named server.crt.

5. Convert the signed client certificate to a PKCS#12 client certificate file using the following command:

   openssl pkcs12 ‑export ‑clcerts ‑in client.CRT ‑inkey client.key ‑out client.P12

   This command includes the client's private key (client.key), and saves the client certificate file in PKCS#12 format, i.e. client.P12. The client certificate needs to be in this format so you can import it into Windows.

6. Copy the CA certificate (client-ca.crt) to the server on which OneSpan Authentication Server is running. This certificate will be used to verify client certificates.

7. Deploy the required certificates to the client, i.e. copy the following files to the client host:

   • client.P12. To be inserted into the Windows Certificate Repository.
   • client.crt. Needed by the C# program.
   • client-ca.crt. Optional. Used by Windows to locally verify the client certificate.

Step 2 (OPTIONAL): Regenerating the OneSpan Authentication Server certificate

If you are using a sha1RSA certificate then you can skip this step.

If you are using a sha256RSA SSL server certificate for OneSpan Authentication Server, then you MUST replace this with a SHA1 certificate, because sha256RSA is not supported by Windows and therefore will not work with .NET clients.

You can generate a new sha1RSA certificate via the OneSpan Authentication Server Maintenance Wizard.

To generate a new SHA1RSA certificate (using OneSpan Authentication Server Maintenance Wizard)

1. Launch the OneSpan Authentication Server Maintenance Wizard.
2. Select the Install SSL Server Certificate option.
3. Click Generate and install a new test certificate (self-signed).

When you have created a new certificate, edit the identikeyconfig.xml file in the OneSpan Authentication Server binary folder, i.e. %PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server\bin. Under SOAP SSL set the supported-cipher-suite field to LOW, e.g.:

<Supported-Cipher-Suite type="string" data="LOW" />

Step 3: Configuring OneSpan Authentication Server to enable client verification

Next, configure OneSpan Authentication Server to verify the .NET SOAP client.

To enable SOAP client verification in OneSpan Authentication Server

1. Create the file %PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server\clientcacerts.pem.
2. Copy the contents of the certification authority (CA) certificate file (client-ca.crt) to clientcacerts.pem.
3. Launch the OneSpan Authentication Server Configuration Utility.

4. Select Communicators > SOAP > Client Certificate Verification > CA Certificate File and point to the new client CA certificate file, i.e. %PROGRAMFILES%\VASCO\IDENTIKEY Authentication Server\clientcacerts.pem.

   You need to do this step each time the Maintenance Wizard is run as the wizard will reset this path back to the default.

5. Select Communicators > SOAP > Client Certificate Verification and set Require Client Certificate to either Required or Required-Signed Address Only, depending on your requirements.
6. Restart OneSpan Authentication Server.

Step 4: Importing the required certificates into the Windows certificate store

The exact procedure for this step may be different depending on the Windows version used.

To import the client certificate and client CA certificate into the Windows certificate store

1. Launch the Microsoft Management Console application.
2. Add the Certificates snap-in for the Local Computer store (see  Installing the certification authority (CA) certificate for the sample website).
3. Import the client.P12 certificate file. Choose Automatically select the certificate store based on the type of certificate.
4. (OPTIONAL) Import the client-ca.crt certificate file. Choose Place all certificates in the following store and select Trusted Root Certification Authorities.

5. Verify that the client certificate is in the Personal > Certificates folder under Certificates (Local Computer).

   You may need to close and then re-open the Certificates snap-in to see the imported certificate, as it does not always automatically refresh.

6. Verify that the client CA certificate is in the Trusted Root Certification Authorities > Certificates folder under Certificates (Local Computer).

   You may need to close and then re-open the Certificates snap-in to see the imported certificate, as it does not always automatically refresh.

Step 5: Creating the C# client

The following procedure uses Visual Studio 2010 to create a C# project, i.e. the C# client. This project will be created using the administration.wsdl file. This file (along with all other WSDL files) is located in sdk_install_dir\wsdl.

Keep in mind that the following procedure is meant to serve as an example to help you create your own SOAP clients.

To create a C# project with a web reference using the administration.wsdl file

1. Create a new C# project in Visual Studio 2010.
2. Right-click Web References and select Add Web Reference.
3. In the URL section, specify the path to the administration.wsdl file, e.g. sdk_install_dir\wsdl\administration.wsdl.
4. Name the web reference administration.

5. Configure the web reference:

   1. Open the app.config file in the C# project.
   2. Locate the setting that refers to a URL. Typically, this should be http://localhost:8888.
   3. Edit this setting to point to the OneSpan Authentication Server host and use the https prefix instead of http.

Step 6: Writing the client logon code

The final step is to write the client logon code. This code should allow the client to connect to OneSpan Authentication Server using the client certificate.

The following code snippet is a good example of client logon code. Note that the doSSLClientVerifyLogon() method in the following code will connect to OneSpan Authentication Server using the client certificate.

using System.Security.Cryptography.X509Certificates;
using SOAPAdminTest.Administration;
using System.Net;
using System.Windows.Forms;

namespace SOAPAdminTest
{
  class SSLClientVerifyLogon
  {
    // Implement the ICertificatePolicy interface
    class CertPolicy : ICertificatePolicy
    {
      public bool CheckValidationResult(ServicePoint srvPoint, X509Certificate certificate, WebRequest request, int certificateProblem)
      {
        // You can do your own certificate checking.
        // You can obtain the error values from WinError.h.
        // Return true so that any certificate will work with this sample.
        return true;
      }
    }

    static public CredentialAttribute[] doSSLClientVerifyLogon()
    {
      Administration.Administration adminObject = new Administration.Administration();
      // Set the certificate policy
      ServicePointManager.CertificatePolicy = new CertPolicy();
      // Load the client certificate from a file.
      // This should point to wherever you have placed your 'client.crt' file
      X509Certificate x509 = X509Certificate.CreateFromCertFile(@"C:\certs\client.crt");
      adminObject.ClientCertificates.Add(x509);
      return logon(adminObject);
    }

    static void showResults(CredentialResults results)
    {
      if (results.resultCodes.returnCode == 0)
      {
        MessageBox.Show("Success!!");
      }
      else
      {
        if (results.resultCodes.returnCode == -1)
        {
          string errorMsg = "";
          foreach (Error error in results.errorStack)
          {
            errorMsg += error.errorDesc;
            errorMsg += "\n";
          }
          MessageBox.Show("Error: " + errorMsg);
        }
        else
          MessageBox.Show("Unknown return code " + results.resultCodes.returnCode);
      }
    }

    static private CredentialAttribute[] logon(Administration.Administration adminObject)
    {
      SOAPAdminTest.Administration.CredentialAttribute[] credAttributes;
      credAttributes = new CredentialAttribute[3];
      int i = 0;
      // Set user name
      credAttributes[i] = new CredentialAttribute();
      credAttributes[i].attributeID = CredentialAttributeIDEnum.CREDFLD_USERID;
      credAttributes[i++].value = "admin";
      // Set password
      credAttributes[i] = new CredentialAttribute();
      credAttributes[i].attributeID = CredentialAttributeIDEnum.CREDFLD_PASSWORD;
      credAttributes[i++].value = "password";
      // Set password format
      credAttributes[i] = new CredentialAttribute();
      credAttributes[i].attributeID = CredentialAttributeIDEnum.CREDFLD_PASSWORD_FORMAT;
      credAttributes[i++].value = 0;
      CredentialResults results = adminObject.logon(credAttributes);
      showResults(results);
      return results.resultAttribute;
    }
  }
}