Preparing for Chrome's Certificate Transparency Policy: Expect-CT With Reporting in ASP.NET Core

Google's Certificate Transparency project is an open framework for monitoring and auditing SSL certificates. The goal of the project is the detection of mis-issued/malicious certificates and the identification of rogue Certificate Authorities. In October 2016, Google announced that Chrome will require compliance with Certificate Transparency. The date for enforcing this requirement was initially set to October 2017 and was later changed to April 2018.

Back in December 2016, the draft of Expect-CT Extension for HTTP has been submitted and quickly followed by a call for adoption. The draft introduces the Expect-CT response header which will allow hosts to either test or enforce the Certificate Transparency policy. The draft has been adopted and is currently in IETF stream, while the header support is already in development for Chrome (the Security Engineering team at Mozilla has also expressed interest in providing this type of support in Firefox in 2017).

In this post, I'm going to show how the Expect-CT response header (and its reporting capabilities) can be set up for ASP.NET Core applications, so when the browser support comes, it can be used for testing your compliance with the Certificate Transparency policy.

Setting the Expect-CT Response Header

The Expect-CT header has three directives defined. The only required one is max-age, which tells the browser for how long it should treat the host as known Expect-CT host. The optional directives are report-uri (which can be used to provide an absolute URI to which the violation report will be sent) and enforce (which results in refusing connections in case of violations). The specification also requires the header to be delivered only over a secure connection.

Assuming one would want to set up a simple report-only scenario, this can easily be done with a simple anonymous middleware.

public void Configure(IApplicationBuilder app)
{
    ...

    app.Use((context, next) =>
    {
        if (context.Request.IsHttps)
        {
            context.Response.Headers.Append("Expect-CT",
                $"max-age=0; report-uri=\"https://example.com/report-ct\"");
        }

        return next.Invoke();
    });

    ...
}

But just set up the header so that it has only  a small value - the real goal is to receive the information when something is wrong.

Receiving Violation Report

If the report-ui directive has been specified as part of the Expect-CT header, and a violation occurs, the client should send the report. The report should be sent using a POST request with a content type of application/expect-ct-report. This means that middleware aiming at receiving the violation report should check for those conditions.

public class ExpectCtReportingMiddleware
{
    private const string _expectCtReportContentType = "application/expect-ct-report";

    private readonly RequestDelegate _next;

    public ExpectCtReportingMiddleware(RequestDelegate next)
    {
        _next = next ?? throw new ArgumentNullException(nameof(next));
    }

    public async Task Invoke(HttpContext context)
    {
        if (IsExpectCtReportRequest(context.Request))
        {
            // TODO: Get the report from request

            context.Response.StatusCode = StatusCodes.Status204NoContent;
        }
        else
        {
            await _next(context);
        }
    }

    private bool IsExpectCtReportRequest(HttpRequest request)
    {
        return HttpMethods.IsPost(request.Method)
            && (request.ContentType == _expectCtReportContentType);
    }
}

The report should be sent as a JSON file, with the top level property of the expect-ct-report containing the violation details. The details contain information like hostname, port, failure time, Expect-CT Host expiration time, certificates chains, and SCTs (I will skip certificates chains and SCTs here as they are hard without real-life examples). Below, I have the code for a sample report:

{
    "expect-ct-report": {
        "date-time": "2017-05-05T12:45:00Z",
        "hostname": "example.com",
        "port": 443,
        "effective-expiration-date": "2017-05-05T12:45:00Z",
        ...
    }
}

Which can be represented with the following class:

public class ExpectCtViolationReport
{
    public DateTime FailureDate { get; set; }

    public string Hostname { get; set; }

    public int Port { get; set; }

    public DateTime EffectiveExpirationDate { get; set; }
}

The middleware needs to parse the request body into an object of this class. The Request.Body is available as a stream so using JsonTextReader form Json.NET seems to be a reasonable approach.

public class ExpectCtReportingMiddleware
{
    ...

    public async Task Invoke(HttpContext context)
    {
        if (IsExpectCtReportRequest(context.Request))
        {
            ExpectCtViolationReport report = null;

            using (StreamReader requestBodyReader = new StreamReader(context.Request.Body))
            {
                using (JsonReader requestBodyJsonReader = new JsonTextReader(requestBodyReader))
                {
                    JsonSerializer serializer = new JsonSerializer();
                    serializer.Converters.Add(new ExpectCtViolationReportJsonConverter());
                    serializer.DateFormatHandling = DateFormatHandling.IsoDateFormat;

                    report = serializer.Deserialize<ExpectCtViolationReport>(requestBodyJsonReader);
                }
            }

            context.Response.StatusCode = StatusCodes.Status204NoContent;
        }
        else
        {
            await _next(context);
        }
    }

    ...
}

The ExpectCtViolationReportJsonConverter takes care of going inside the expect-ct-report property and deserializing the object. I'm skipping its code here, it can be found on GitHub.

The next thing we need to do is propagate of the violation report outside of the middleware. For this, a simple service will be sufficient:

public interface IExpectCtReportingService
{
    Task OnExpectCtViolationAsync(ExpectCtViolationReport report);
}

The middleware shouldn't make any assumptions about this service's lifetime, so it is safer to grab it directly from HttpContext.RequestServiceswhen needed, instead of relying on a constructor injection (which would result in the service being treated as a singleton by the middleware).

public class ExpectCtReportingMiddleware
{
    ...

    public async Task Invoke(HttpContext context)
    {
        if (IsExpectCtReportRequest(context.Request))
        {
            ExpectCtViolationReport report = null;

            ...

            if (report != null)
            {
                IExpectCtReportingService expectCtReportingService =
                    context.RequestServices.GetRequiredService<IExpectCtReportingService>();

                await expectCtReportingService.OnExpectCtViolationAsync(report);
            }

            context.Response.StatusCode = StatusCodes.Status204NoContent;
        }
        else
        {
            await _next(context);
        }
    }

    ...
}

The only thing missing is an implementation of IExpectCtReportingService. Below is a very simple one which uses the ASP.NET Core logging API.

public class LoggerExpectCtReportingService : IExpectCtReportingService
{
    private readonly ILogger _logger;

    public LoggerSecurityHeadersReportingService(ILogger<IExpectCtReportingService> logger)
    {
        _logger = logger;
    }

    public Task OnExpectCtViolationAsync(ExpectCtViolationReport report)
    {
        _logger.LogWarning("Expect-CT Violation: Failure Date: {FailureDate} UTC"
            + " | Effective Expiration Date: {EffectiveExpirationDate} UTC"
            + " | Host: {Host} | Port: {Port}",
            report.FailureDate.ToUniversalTime(),
            report.EffectiveExpirationDate.ToUniversalTime(),
            report.Hostname,
            report.Port);

        return Task.FromResult(0);
    }
}

Now everything can be wired up as part of the pipeline configuration.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient<IExpectCtReportingService, LoggerExpectCtReportingService>();
        ...
    }

    public void Configure(IApplicationBuilder app, ILoggerFactory loggerFactory)
    {
        loggerFactory.AddConsole();
        loggerFactory.AddDebug();

        ...

        app.Use((context, next) =>
        {
            if (context.Request.IsHttps)
            {
                context.Response.Headers.Append("Expect-CT",
                    $"max-age=0; report-uri=\"https://example.com/report-ct\"");
            }

            return next.Invoke();
        })
        .Map("/report-ct", branchedApp => branchedApp.UseMiddleware<ExpectCtReportingMiddleware>());

        ...
    }
}

Ready for the Future

This post talks about things which are not quite there yet but are coming and we should be prepared. My personal suggestion for when the support for header arrives would be to set up Expect-CT header in report-only mode and then slowly upgrade to enforcing it.

I've made the functionality described here available as part of my security side project through SecurityHeadersMiddleware, ExpectCtReportingMiddleware and  ISecurityHeadersReportingService.