From 61f7fe399a45472ca73a7b373b756596e80b3d38 Mon Sep 17 00:00:00 2001 From: Andreas Auernhammer Date: Sat, 20 Dec 2025 22:12:13 +0100 Subject: [PATCH] update README and add TLS handshake svg This commit adds a brief summary of the `mtls` module and a svg image showing the "regular" and mutual TLS handshake, and how clients resp. servers verify their peer's identity. Signed-off-by: Andreas Auernhammer --- .github/tls-handshakes.svg | 4 ++++ README.md | 41 ++++++++++++++++++++++++++++++++++---- 2 files changed, 41 insertions(+), 4 deletions(-) create mode 100644 .github/tls-handshakes.svg diff --git a/.github/tls-handshakes.svg b/.github/tls-handshakes.svg new file mode 100644 index 0000000..4ad783d --- /dev/null +++ b/.github/tls-handshakes.svg @@ -0,0 +1,4 @@ + + +ClientServerpub_key_serverClientHelloidentity_server Hash( pub_key_server)==ClientServerpub_key_serverpub_key_clientidentity_server Hash( pub_key_server)==identity_client Hash( pub_key_client)==TLS Handshake ( server authenticates to client )Mutual TLS Handshake ( client auth. to server and server auth. to client ) \ No newline at end of file diff --git a/README.md b/README.md index 84db9af..2ac117a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,45 @@ [![Go Reference](https://pkg.go.dev/badge/aead.dev/mtls.svg)](https://pkg.go.dev/aead.dev/mtls) -# Mutual TLS +# [m]TLS -## Install +A Go library for TLS/HTTPS using public key pinning instead of certificate authorities. + +**The Problem** + +Usually TLS/HTTPS relies on certificate authorities (CAs) to establish trust. This means: +- Obtaining and renewing certificates from CAs +- Managing certificate chains and trust stores +- Trusting any certificate signed by a trusted CA + +For services that communicate with known peers, for example a web and DB server, this is overkill. + +**The Solution** + +This library takes an SSH-like approach to TLS authentication. Just like SSH's `known_hosts` file lets you trust +specific server keys directly, `mtls` lets you identify peers by their public key hash rather than CA signatures. + +``` +h1:2eYrKRe4K9Xf_HjOhdJjNPuH5P8sLN9XNgdgZKfqt1A +``` + +That's it. No certificates to issue, no chains to verify, no CAs to manage. + +## Getting Started ```sh go get aead.dev/mtls@latest ``` -The [documentation](https://pkg.go.dev/aead.dev/mtls) contains some [examples](https://pkg.go.dev/aead.dev/mtls#pkg-examples) -for TLS clients and servers to get started. +This downloads the `mtls` module. It has no dependencies. + +Add the `aead.dev/mtls` module to your `go.mod` file. +The documentation contains [examples](https://pkg.go.dev/aead.dev/mtls#example-package) on how to configure clients and servers. + +## How It Works + +1. Generate a private/public key pair. +2. Peers exchange identities (SHA-256 hash of public key) out-of-band. + For example, as part of their configuration. +3. During the TLS handshake, one or both sides verify that the other's public key matches the expected identity. + +![TLS Handshakes](./.github/tls-handshakes.svg)