Disabling Client Certificate Revocation Checks in a Web Role

Background

The most common form of SSL in the context of HTTP communications is what's commonly referred to as one-way SSL in which only the server presents an SSL certificate and this certificate is used both for verifying the identity of the server and for encrypting the traffic in both directions.

However, there is also two-way SSL in which both server and client each brings their own certificate to the SSL handshake process and these certificates are used to facilitate mutual authentication. This is normally used as a highly secure way to authenticate clients, either as the only form of client authentication, or in combination with traditional password credentials.

Both server certificates and client certificates are usually subject to something called revocation check. This is a process during which each party checks the certificate presented by the other party against a certificate revocation list (CRL) published by the issuer of that certificate and downloaded periodically over HTTP or LDAP, to determine whether the certificate has been revoked. If the thumbprint of the presented certificate is on the list, the SSL handshake fails. Revocation checks can also be performed in a more direct manner with a real-time call to the issuer using a protocol called OCSP.

In some scenarios involving two-way SSL, it is necessary to configure the web server to not perform this revocation check. There could be any number of reasons for this. For example, you may have chosen to use client certificates whose issuer does not publish revocation information, or your web server may not be able to download this revocation information due to connectivity reasons.

Disabling client certificate revocation checks in a web role is an IIS configuration change. In my previous post Making IIS Configuration Changes in a Web Role Startup Task I explained that some such configuration changes are quite tricky to do due to the way startup tasks and the initial IIS configuration are sequenced. Disabling client certificate revocation checks is a good example of such a change, so let's look at how you how you can apply that method for this specific purpose.

Solution

These are the basic steps you will want to perfom in your cloud service project:

  1. Add a PowerShell script DisableClientCertRevocationCheck.ps1 that will ultimately make the IIS configuration change.
  2. Add a scheduled task definition XML file DisableClientCertRevocationCheck.xml from which the scheduled task will be created.
  3. Add a PowerShell script RegisterScheduledTasks.ps1 to register the scheduled task with Windows Task Scheduler.
  4. Add the usual RunStartupScripts.cmd file to act as the main entry point for your startup task.
  5. Add the usual <Task> element in your ServiceDefinition.csdef file to declare the startup task.

Steps 2-5 are generic and described in detail in my previous post, so I won't go through that again here. The PowerShell script used for step 1 is what's interesting here; to disable client certificate revocation checks in IIS from PowerShell, we can use a script such as the following:

$ip = (Get-WmiObject Win32_NetworkAdapterConfiguration | ? { $_.IPAddress -ne $null }).IPAddress[0]
$ipport = $ip + ":443"

$outputArray = netsh http show sslcert $ipport
$outputString = [system.String]::Join(";", $outputArray)
$outputString -match "Certificate Hash\s*:\s(\w+)"
$certHash = $matches[1]
$outputString -match "Application ID\s*:\s\{(.*)\}"
$appId = "{" + $matches[1] + "}"

netsh http delete sslcert $ipport
netsh http add sslcert ipport=$ipport appid=$appId certhash=$certHash certstorename=MY verifyclientcertrevocation=disable

Let's take a look at this script in more detail:

  • Lines 1-2 aquire the configured IP address of the role instance. This is necessary because this is how the SSL binding is identified.
  • Lines 4-9 executes the command netsh http show sslcert command to output information about the configured SSL binding, and applies some regex matching to extract the certificate thumbprint and application GUID from it.
  • Line 11 deletes the existing SSL binding.
  • Line 12 recreates the SSL binding using the same parameters (certificate thumbprint and application GUID) that it had before, but this time adding the verifyclientcertrevocation=disable parameter.

If you tried running this script directly from a web role startup task, it would fail because no SSL binding would exist yet, since at that point in time the service runtime will not yet have finished setting up the sites and bindings in IIS. By leveraging this method of deferring the execution until IIS setup has been finalized, we can reliably execute this script without introducing artifical delays.

1 comment

Leave a comment