req-mtls

Repository presenting authentication for orchestrated agents navigating the web. It implements all components required by request mTLS defined by draft-jhoyla-req-mtls-flag, and presents examples.

Tables of Content

• Examples
• Usage
  • Prerequisites
  • Connecting to a remote test server
  • Setup a local environment
  • Connecting to your local environment
  • Setup without Docker
• Security Considerations
• License

Examples

We provide example code in Go in the cmd folder. This leverages the Cloudflare Research implementation of request mTLS as part of a Go fork in cloudflare/go.

For convenience, a demonstration is provided on req-mtls.research.cloudflare.com, which you can test against.

In the assets folder, you can find a packet capture demonstrating a successful req mTLS connection. The packet was captured with the SSLKEYLOGFILE environment variable set.

Usage

Prerequisites

• Docker
• Docker Compose
• Make
• OpenSSL

Connecting to a remote test server

The demonstration client and server are both built and run inside docker containers. You can connect to req-mtls.research.cloudflare.com demonstration server by running the following command.

make client-request

This will spin up a test client in a docker container and connect to our demonstration server.

Setup a local environment

When interacting with Cloudflare demonstration, certificates are already provided.

To do the same with a local demo, you need to generate these certificates yourself.

You can do this with

make gen-cert

This creates a client CA and generate a client leaf cert from it. The default is to use the RFC 9500 test keys for the client CA key. This allows anyone to create client certificates that will correctly chain to the client CA in the demo.

Connecting to your local environment

You can run the local test server with

make start-test-server

This then allows you to run a client request hitting the /debug endpoint of the server

make client-request-local

Setup without Docker

If you want to run the client and server directly as opposed to in docker you can build them locally by

make artefacts

This will build the client and server binaries and place them in the bin directory.

For example to connect to Cloudflare's demonstration site and request mutually authenticated TLS you can run:

./bin/client \
  -cert "./testdata/certs/client.crt" \
  -key "./testdata/certs/client.key" \
  -connect "https://req-mtls.research.cloudflare.com/debug" \
  -tlsflags 80

You can send other flags than the req mTLS flag

./bin/client \
  -cert "./testdata/certs/client.crt" \
  -key "./testdata/certs/client.key" \
  -connect "https://req-mtls.research.cloudflare.com/debug" \
  -tlsflags 8,170,12

Or set a custom root certificate for the server

./bin/client \
  -cert "./testdata/certs/client.crt" \
  -key "./testdata/certs/client.key" \
  -connect "https://req-mtls.research.cloudflare.com/debug" \
  -server-cacert "./testdata/certs/rootCA.crt" \
  -tlsflags 80

Security Considerations

This software has not been audited. Please use at your sole discretion.

Cryptographic keys

All keys shared publicly as part of this repository are test keys provided by RFC 9500, and formatted in thibmeu/rfc9500. They MUST NOT be used for production services.

TLS certificate provision

The repository include certbot-to-R2, a tool for generating a certificate for a given FQDN and uploading it to a Cloudflare R2 bucket. This is useful for deploying a demo. We advise against the use of this service in production.

License

This project is under the Apache 2.0 license.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you shall be Apache 2.0 licensed as above, without any additional terms or conditions.