newspaint

Documenting Problems That Were Difficult To Find The Answer To

Checking SSL Certificate Expiry on Remote Server using PowerShell

Overview

There are a number of approaches to take to get the expiry time of the SSL certificate on a remote server using PowerShell. This tutorial will be conducted using PowerShell 2.0 and .NET 3.5 for maximum compatibility (as there are some organisations out there still using Microsoft Windows 2003).

The Simple Way

If you’re reasonably assured your remote server exists and you have connectivity to it then you can write a simple script to:

  • make a TCP connection to the SSL port of the host you wish to check
  • obtain a SSL stream from the TCP connection
  • SSL authenticate as a client
  • obtain the X509 certificate of the remote server from the SSL stream
  • obtain the NotAfter field from the X509 certificate

That script is as follows:

Set-StrictMode -Version 2.0

#Requires -Version 2.0

$HostName = "www.google.com"
$Port = 443

# get TCP connection
[System.Net.Sockets.TcpClient]$TcpClient = $null
$TcpClient = New-Object "System.Net.Sockets.TcpClient"
try {
    $TcpClient.Connect( [System.String]$HostName, [System.Int32]$Port )
} catch {
    Throw "TCP connection error: $_"
}

# get SSL stream from TCP connection
[System.Net.Security.SslStream]$SslStream = $null
$SslStream = $TcpClient.GetStream()

# authenticate SSL stream
try {
    $SslStream.AuthenticateAsClient( $HostName )
} catch {
    Throw "Failed to authenticate SSL stream: $_"
}

# get X509 certificate
[System.Security.Cryptography.X509Certificates.X509Certificate]$cert = $null
$cert = $SslStream.RemoteCertificate

# get X509 certificate with extra properties
[System.Security.Cryptography.X509Certificates.X509Certificate2]$cer2 = $null
$cer2 = New-Object "System.Security.Cryptography.X509Certificates.X509Certificate2" -ArgumentList $cert

# output expiry
$cer2.NotAfter

# close stream and connection
$SslStream.Close()
$TcpClient.Close()

Implementing Timeouts

The fact is that some operations will take a long time when things go wrong. In the code above there are two moments things can block for a long time: making a TCP connection (if the remote end is not responding or the firewall is consuming network traffic), and authenticating the SSL stream (when, for example, the connected service is not SSL and doesn’t response to the authentication process).

In PowerShell we can use the Begin/End form of operations and wait up to a specified number of milliseconds (time) before we give up. The code to do that follows:


Set-StrictMode -Version 2.0

#Requires -Version 2.0

$HostName = "www.google.com"
$Port = 443

# get TCP connection
[System.Net.Sockets.TcpClient]$TcpClient = $null
$TcpClient = New-Object "System.Net.Sockets.TcpClient"
[System.IAsyncResult]$IAsyncResult = $TcpClient.BeginConnect(
    [String]$HostName,
    [System.Int32]$Port,
    $null, # AsyncCallback
    $null # user-defined Object
)

[System.Threading.ManualResetEvent]$AsyncWaitHandle = $null
$AsyncWaitHandle = $IAsyncResult.AsyncWaitHandle

[System.Boolean]$Wait = $AsyncWaitHandle.WaitOne( 5000 ) # 5s timeout

if ( $Wait ) {
    # object was signalled, i.e. connect finished or errored
    try {
        $TcpClient.EndConnect( $IAsyncResult )
        if ( -not $TcpClient.Connected ) {
            Throw "TCP connection not connected!"
        }
    } catch {
        Throw "TCP connection error: $_"
    }
} else {
    # timeout
    $TcpClient.Close() # can't wait for EndConnect, so destroy client
    Throw "TCP connection TIMEOUT"
}

# get SSL stream from TCP connection
[System.Net.Security.SslStream]$SslStream = $null
$SslStream = $TcpClient.GetStream()

# authenticate SSL stream
[System.IAsyncResult]$IAsyncResult = $SslStream.BeginAuthenticateAsClient(
    [String]$HostName,
    $null, # AsyncCallback
    $null # user-defined Object
)

[System.Threading.ManualResetEvent]$AsyncWaitHandle = $null
$AsyncWaitHandle = $IAsyncResult.AsyncWaitHandle

[System.Boolean]$Wait = $AsyncWaitHandle.WaitOne( 5000 ) # 5s timeout

if ( $Wait ) {
    # object was signalled, i.e. authenticate finished or errored
    try {
        $SslStream.EndAuthenticateAsClient( $IAsyncResult )
    } catch {
        Throw "SSL authentication error: $_"
    }
} else {
    # timeout
    $SslStream.Close() # can't wait for authenticate, so destroy stream
    $TcpClient.Close() # close TCP connection
    Throw "SSL authentication TIMEOUT"
}

# get X509 certificate
[System.Security.Cryptography.X509Certificates.X509Certificate]$cert = $null
$cert = $SslStream.RemoteCertificate

# get X509 certificate with extra properties
[System.Security.Cryptography.X509Certificates.X509Certificate2]$cer2 = $null
$cer2 = New-Object "System.Security.Cryptography.X509Certificates.X509Certificate2" -ArgumentList $cert

# output expiry
$cer2.NotAfter

# close stream and connection
$SslStream.Close()
$TcpClient.Close()

Not Requiring Validation of SSL Certification

So, you want to check a SSL certificate’s expiry date, and you don’t really care what the name is on the remote server certificate. You will be getting validation errors by now, like the following:

Exception calling "AuthenticateAsClient" with "1" argument(s): "The remote certificate is invalid according to the validation procedure."

You replace the following lines of code:

# get SSL stream from TCP connection
[System.Net.Security.SslStream]$SslStream = $null
$SslStream = $TcpClient.GetStream()

with:

# get SSL stream from TCP connection
[System.Net.Security.SslStream]$SslStream = $null
$SslStream = New-Object System.Net.Security.SslStream(
    $TcpClient.GetStream(),
    $True,
    [System.Net.Security.RemoteCertificateValidationCallback]{ $true }
)

This works fine on the first code example given above without timeouts.

But for the asynchronous code with timeouts this attempt to bypass certificate validation gives the error:

SSL authentication error: Exception calling "EndAuthenticateAsClient" with "1" argument(s): "There is no Runspace available to run scripts in this thread. You can provide one in the DefaultRunspace property of the System.Management.Automation.Runspaces.Runspace type. The script block you attempted to invoke was:  $true "

Okay things are quickly becoming rather tricky rather fast. The issue has been explained elsewhere as:

Asynchronous callback delegates are not a friend to PowerShell. They are serviced by the .NET threadpool which means that if they point to script blocks, there will be no Runspace available to execute them. Runspaces are thread-local resources in the PowerShell threadpool. The .NET threadpool, operating independently, is not too interested in coordinating callbacks with PowerShell. So what do we do?

We’re basically forced to drop into C#/.NET world whether we like it or not. So we might as well provide our own simple class that creates the appropriate callback function.

Add-Type @'
public class MyNoValidate {
  private static System.Boolean bypassvalidation(
    System.Object sender,
    System.Security.Cryptography.X509Certificates.X509Certificate certificate,
    System.Security.Cryptography.X509Certificates.X509Chain chain,
    System.Net.Security.SslPolicyErrors sslPolicyErrors
  ) {
    return true;
  }

  public static System.Net.Security.RemoteCertificateValidationCallback getcallback() {
    System.Net.Security.RemoteCertificateValidationCallback cb;

    cb = new System.Net.Security.RemoteCertificateValidationCallback(
      bypassvalidation
    );

    return cb;
  }
}
'@

and then:

# get SSL stream from TCP connection
[System.Net.Security.SslStream]$SslStream = $null
[System.Net.Security.RemoteCertificateValidationCallback]$Callback = $null
$Callback = [MyNoValidate]::getcallback()
$SslStream = New-Object System.Net.Security.SslStream(
    $TcpClient.GetStream(),
    $True,
    $Callback
)

Now you can get your SSL certificate without having to know the name on the certificate first – with timeouts, too!

Final Note

When getting the expiry time of a SSL certificate please avoid (don’t use) the System.Security.Cryptography.X509Certificates.X509Certificate2.GetExpirationDateString() method! You cannot be sure what you’re getting – whether the date is in USA format or the rest of the world format, or local or UTC time. Much, much better to use the System.Security.Cryptography.X509Certificates.X509Certificate2.NotAfter property of type System.DateTime.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: