Cats.CertificateTransparency 5.0.1

Certificate Transparency for .NET

C# .NET port of,

• certificate-transparency-java
• babylonhealth/certificate-transparency-android

    Install-Package Cats.CertificateTransparency

Blog Post

The library is designed to be dependency-injection friendly; every service class has a matching interface. However, to get things running quickly, there is also a static Instance class which constructs lazy singletons for both ILogListService and CertificateTransparencyVerifier.

If you want to provide a custom list of included and excluded domains to these static instances, call Instance.InitDomains first. By default, validation is enabled for all TLS-secured domains.

Instance.InitDomains(new [] { "*.google.com", "microsoft.com" }, new [] { "nuget.org" });

Examples

.NET

var client = new HttpClient(new HttpClientHandler()
{
    ServerCertificateCustomValidationCallback = (request, certificate, chain, sslPolicyErrors) =>
    {
        var certificateChain = chain.ChainElements.OfType<X509ChainElement>().Select(i => i.Certificate).ToList();
        var certificateVerifier = Cats.CertificateTransparency.Instance.CertificateTransparencyVerifier;
        var ctValueTask = certificateVerifier.IsValidAsync(request.RequestUri.Host, certificateChain, CancellationToken.None);

        var ctResult = ctValueTask.IsCompleted
            ? ctValueTask.Result
            : ctValueTask.AsTask().Result;

        return ctResult.IsValid;
    }
});

Android

For applications targeting Android versions prior to Android 16, the Android implementation can be used:

bool VerifyCtResult(string hostname, IList<DotNetX509Certificate> certificateChain, CtVerificationResult result)
{
    // Fail open if the CT log list is unreachable.
    if (result == CtResult.LogServersFailed)
    {
        return true;
    }

    // Add any additional checks or logging here.
    return result.IsValid;
}

var httpHandler = new Cats.CertificateTransparency.CatsAndroidClientHandler(VerifyCtResult);
var client = new HttpClient(httpHandler);

iOS

There is currently no platform specific implementation for iOS. Certificate transparency is already enabled since iOS 12.1.1, however, it can be disabled per domain via a property list setting NSRequiresCertificateTransparency.

If you are keen you could use the CertificateVerifier to build your own HttpClientHandler, similar to the included Android implementation.

Log Lists

A CT log list contains the Certificate Transparency logs that are trusted for verification.

For production applications, maintaining your own log list is recommended. Your application then controls:

• Which CT logs are trusted.
• Where the log list is hosted.
• The availability of the log list.
• Updates to the log list.
• The format and schema used by your application.

Using Google's Chrome log list is convenient but creates a dependency on infrastructure that is outside the control of this project. Google may change or restrict access to the list without notice, and applications should expect the Chrome log list to break eventually.

If you maintain your own log list, configure the library to use it through the appropriate ILogListService implementation.

Contributions

Any contributions are welcome! Especially extra test cases!