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

Back in December 2016 the draft of Expect-CT Extension for HTTP has been submitted and quickly followed by 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 currently is 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 the 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 application, so when the browser support comes it can be used for testing compliance with 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 absolute URI to which the violation report will be send) and enforce (which presence results in refusing connections in case of violation). Specification also requires the header to be delivered only over 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 setting up the header has little 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 Expect-CT header and the violation occurs the client should send the report. The report should be sent using POST request with 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 send as JSON with expect-ct-report top level property 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). Sample report could look like below.

{
    "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 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 object of this class. The Request.Body is available as 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 which is needed is propagation of the violation report outside of the middleware. For this purpose a simple service will be sufficient.

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

The middleware shouldn't make any assumptions about this service lifetime, so it is safer to grab it directly from HttpContext.RequestServices when needed instead of relying on constructor injection (which would result in service being treated as singleton by 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 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 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.

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