Lesson 7 of 15 · 40 min

Mutual TLS - Both Sides Prove Who They Are

Require a certificate from the caller as well as the server, read a verified service name off the connection, and delete the shared password from your codebase entirely.

Learning objectives

Explain why proving possession of a private key beats transmitting a secret.
Name the three handshake messages mutual TLS adds and what each one proves.
Configure mutual TLS in Go and in Node, and name the setting that makes it mutual.
Read a caller's verified identity from the TLS layer instead of a header.
Distinguish a claim the caller asserts from a fact the handshake proved.

The one-word change

Question	Answer
Does the client send its private key?	No. It signs the conversation, same as the server did
Can the server replay that signature elsewhere?	No. It only covers this one conversation
What does the server check?	Chain signed by a trusted CA, then the signature
Where does this happen?	During the handshake, before any HTTP exists

main.goGo

// tlsConfig builds ONE config used in both directions:
//
//	Certificates -> the identity we present, whichever role we are in
//	RootCAs      -> whose certificates we accept when WE are the client
//	ClientCAs    -> whose certificates we accept when WE are the server
//	ClientAuth   -> the switch that makes this MUTUAL instead of ordinary TLS
func tlsConfig() (*tls.Config, error) {
	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
	if err != nil {
		return nil, err
	}
	pem, err := os.ReadFile(caFile)
	if err != nil {
		return nil, err
	}
	pool := x509.NewCertPool()
	if !pool.AppendCertsFromPEM(pem) {
		return nil, fmt.Errorf("no certificates found in %s", caFile)
	}
	return &tls.Config{
		Certificates: []tls.Certificate{cert},
		RootCAs:      pool,
		ClientCAs:    pool,
		ClientAuth:   tls.RequireAndVerifyClientCert, // no cert, no request
		MinVersion:   tls.VersionTLS13,
	}, nil
}

main.goGo

func health(w http.ResponseWriter, r *http.Request) {
	// This handler only ever runs for a caller whose certificate already passed
	// the handshake. So the CN below is VERIFIED identity -- not a header the
	// caller typed in and not a shared secret anyone could copy.
	caller := r.TLS.PeerCertificates[0].Subject.CommonName
	log.Printf("<-  %-13s GET /health", caller)

	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(map[string]string{
		"service": "go",
		"status":  "ok",
		"caller":  caller,
	})
}

main.goGo

func poll(cfg *tls.Config) {
	client := &http.Client{
		Timeout:   3 * time.Second,
		Transport: &http.Transport{TLSClientConfig: cfg},
	}

	for {
		time.Sleep(3 * time.Second)

		resp, err := client.Get(peerURL) // back to plain Get -- no headers needed
		if err != nil {
			log.Printf("--> ts            unreachable: %v", err)
			continue
		}

		body, err := io.ReadAll(resp.Body)
		resp.Body.Close()
		if err != nil {
			log.Printf("--> ts            reply unreadable: %v", err)
			continue
		}

		log.Printf("--> ts            %s %s", resp.Status, strings.TrimSpace(string(body)))
	}
}

main.goGo

func main() {
	log.SetFlags(log.Ltime)

	cfg, err := tlsConfig()
	if err != nil {
		log.Fatalf("tls setup failed (run ./gen-certs.sh first): %v", err)
	}

	mux := http.NewServeMux()
	mux.HandleFunc("/health", health)

	srv := &http.Server{
		Addr:      "127.0.0.1:" + port,
		Handler:   mux,
		TLSConfig: cfg,
	}

	fmt.Printf("The Go Server is running on port %s  (https, mTLS required)\n", port)
	go poll(cfg.Clone())

	// The certificate comes from TLSConfig now, so both arguments stay empty.
	log.Fatal(srv.ListenAndServeTLS("", ""))
}

main.goGo

package main

import (
	"crypto/tls"
	"crypto/x509"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
	"strings"
	"time"
)

const (
	port    = "8443"
	peerURL = "https://127.0.0.1:8444/health"

	caFile   = "certs/ca.crt"
	certFile = "certs/go.crt"
	keyFile  = "certs/go.key"
)

// tlsConfig builds ONE config used in both directions:
//
//	Certificates -> the identity we present, whichever role we are in
//	RootCAs      -> whose certificates we accept when WE are the client
//	ClientCAs    -> whose certificates we accept when WE are the server
//	ClientAuth   -> the switch that makes this MUTUAL instead of ordinary TLS
func tlsConfig() (*tls.Config, error) {
	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
	if err != nil {
		return nil, err
	}
	pem, err := os.ReadFile(caFile)
	if err != nil {
		return nil, err
	}
	pool := x509.NewCertPool()
	if !pool.AppendCertsFromPEM(pem) {
		return nil, fmt.Errorf("no certificates found in %s", caFile)
	}
	return &tls.Config{
		Certificates: []tls.Certificate{cert},
		RootCAs:      pool,
		ClientCAs:    pool,
		ClientAuth:   tls.RequireAndVerifyClientCert, // no cert, no request
		MinVersion:   tls.VersionTLS13,
	}, nil
}

func health(w http.ResponseWriter, r *http.Request) {
	// This handler only ever runs for a caller whose certificate already passed
	// the handshake. So the CN below is VERIFIED identity -- not a header the
	// caller typed in and not a shared secret anyone could copy.
	caller := r.TLS.PeerCertificates[0].Subject.CommonName
	log.Printf("<-  %-13s GET /health", caller)

	w.Header().Set("Content-Type", "application/json")
	_ = json.NewEncoder(w).Encode(map[string]string{
		"service": "go",
		"status":  "ok",
		"caller":  caller,
	})
}

func poll(cfg *tls.Config) {
	// Same config as the server side. Because it carries Certificates, this
	// client automatically presents our cert when the peer asks for one.
	client := &http.Client{
		Timeout:   3 * time.Second,
		Transport: &http.Transport{TLSClientConfig: cfg},
	}

	for {
		time.Sleep(3 * time.Second)

		resp, err := client.Get(peerURL)
		if err != nil {
			log.Printf("--> ts            unreachable: %v", err)
			continue
		}

		body, err := io.ReadAll(resp.Body)
		resp.Body.Close()
		if err != nil {
			log.Printf("--> ts            reply unreadable: %v", err)
			continue
		}

		log.Printf("--> ts            %s %s", resp.Status, strings.TrimSpace(string(body)))
	}
}

func main() {
	log.SetFlags(log.Ltime)

	cfg, err := tlsConfig()
	if err != nil {
		log.Fatalf("tls setup failed (run ./gen-certs.sh first): %v", err)
	}

	mux := http.NewServeMux()
	mux.HandleFunc("/health", health)

	srv := &http.Server{
		Addr:      "127.0.0.1:" + port,
		Handler:   mux,
		TLSConfig: cfg,
	}

	fmt.Printf("The Go Server is running on port %s  (https, mTLS required)\n", port)
	go poll(cfg.Clone())

	// The certificate comes from TLSConfig now, so both arguments stay empty.
	log.Fatal(srv.ListenAndServeTLS("", ""))
}

server.tsTypeScript

import { createServer, request } from "node:https";
import { readFileSync } from "node:fs";
import type { TLSSocket } from "node:tls"; // NEW

const ca = readFileSync("certs/ca.crt");
const cert = readFileSync("certs/ts.crt");
const key = readFileSync("certs/ts.key");
// Every outbound call gets a deadline and a size cap. Node gives you neither
// by default: without them, a peer that accepts the connection and then goes
// quiet holds a request open forever.
const REQUEST_TIMEOUT_MS = 3000;
const MAX_RESPONSE_BYTES = 64 * 1024;

server.tsTypeScript

const server = createServer(
  {
    cert,
    key,
    ca,                       // whose client certificates we accept
    requestCert: true,        // ask the caller for one
    rejectUnauthorized: true, // <- the switch that means "mutual"
    minVersion: "TLSv1.3",
  },
  (req, res) => {
    /* handler below */
  },
);

server.tsTypeScript

const socket = req.socket as TLSSocket;
const caller = socket.getPeerCertificate().subject.CN;

log(`<-  ${caller.padEnd(13)} GET /health`);

res.writeHead(200, { "Content-Type": "application/json" });
res.end(JSON.stringify({ service: "typescript", status: "ok", caller }));

server.tsTypeScript

function httpsGet(url: string): Promise<{ status: number; body: string }> {
  return new Promise((resolve, reject) => {
    // cert + key are new here: we now present OUR identity when we call out.
    const req = request(url, { ca, cert, key, minVersion: "TLSv1.3" }, (res) => {
      let body = "";
      let received = 0;
      res.on("data", (chunk) => {
        // Count BYTES off the wire. `string.length` counts UTF-16
        // code units after decoding, which is a different number.
        received += chunk.length;
        if (received > MAX_RESPONSE_BYTES) {
          req.destroy(new Error("response too large"));
          return;
        }
        body += chunk;
      });
      res.on("end", () => {
        clearTimeout(deadline);
        resolve({ status: res.statusCode ?? 0, body });
      });
    });
    const deadline = setTimeout(
      () => req.destroy(new Error("request deadline exceeded")),
      REQUEST_TIMEOUT_MS,
    );
    req.on("error", (error) => {
      clearTimeout(deadline);
      reject(error);
    });
    req.end();
  });
}

server.tsTypeScript

// A rejected handshake is normal output here, not a crash.
server.on("tlsClientError", (error) => {
  log(`!!  handshake rejected: ${error.message}`);
});

server.tsTypeScript

import { createServer, request } from "node:https";
import { readFileSync } from "node:fs";
import type { TLSSocket } from "node:tls";

const PORT = 8444;
const PEER_URL = "https://127.0.0.1:8443/health";

const ca = readFileSync("certs/ca.crt");
const cert = readFileSync("certs/ts.crt");
const key = readFileSync("certs/ts.key");
// Every outbound call gets a deadline and a size cap. Node gives you neither
// by default: without them, a peer that accepts the connection and then goes
// quiet holds a request open forever.
const REQUEST_TIMEOUT_MS = 3000;
const MAX_RESPONSE_BYTES = 64 * 1024;

function log(message: string) {
  console.log(new Date().toTimeString().slice(0, 8), message);
}

function httpsGet(url: string): Promise<{ status: number; body: string }> {
  return new Promise((resolve, reject) => {
    // cert + key are new here: we now present OUR identity when we call out.
    const req = request(url, { ca, cert, key, minVersion: "TLSv1.3" }, (res) => {
      let body = "";
      let received = 0;
      res.on("data", (chunk) => {
        // Count BYTES off the wire. `string.length` counts UTF-16
        // code units after decoding, which is a different number.
        received += chunk.length;
        if (received > MAX_RESPONSE_BYTES) {
          req.destroy(new Error("response too large"));
          return;
        }
        body += chunk;
      });
      res.on("end", () => {
        clearTimeout(deadline);
        resolve({ status: res.statusCode ?? 0, body });
      });
    });
    const deadline = setTimeout(
      () => req.destroy(new Error("request deadline exceeded")),
      REQUEST_TIMEOUT_MS,
    );
    req.on("error", (error) => {
      clearTimeout(deadline);
      reject(error);
    });
    req.end();
  });
}

const server = createServer(
  {
    cert,
    key,
    ca,                       // whose client certificates we accept
    requestCert: true,        // ask the caller for one
    rejectUnauthorized: true, // <- the switch that means "mutual"
    minVersion: "TLSv1.3",
  },
  (req, res) => {
    if (req.url !== "/health") {
      res.writeHead(404);
      res.end();
      return;
    }

    // This handler only ever runs for a caller whose certificate already passed
    // the handshake. So this CN is VERIFIED identity -- not a header the caller
    // typed in, and not a shared secret anyone could copy.
    const socket = req.socket as TLSSocket;
    const caller = socket.getPeerCertificate().subject.CN;

    log(`<-  ${caller.padEnd(13)} GET /health`);

    res.writeHead(200, { "Content-Type": "application/json" });
    res.end(JSON.stringify({ service: "typescript", status: "ok", caller }));
  },
);

// A rejected handshake is normal output here, not a crash.
server.on("tlsClientError", (error) => {
  log(`!!  handshake rejected: ${error.message}`);
});

async function poll() {
  while (true) {
    await new Promise((r) => setTimeout(r, 3000));
    try {
      const res = await httpsGet(PEER_URL);
      log(`--> go            ${res.status} ${res.body.trim()}`);
    } catch (error) {
      log(`--> go            unreachable: ${error}`);
    }
  }
}

server.listen(PORT, "127.0.0.1", () => {
  console.log(`The TypeScript Server is running on port ${PORT}  (https, mTLS required)`);
  poll();
});

go output

The Go Server is running on port 8443  (https, mTLS required)
17:23:40 <-  ts-server     GET /health
17:23:40 --> ts            200 OK {"service":"typescript","status":"ok","caller":"go-server"}

Lesson	The receiving service logs	Because
2	`(unknown)`	Nothing identified the caller
3 to 6	`(has key)`	The caller held a copyable string
7	`ts-server`	A name read off a verified certificate

Weakness in Lesson 4	Status now
Key travels in plain text	The private key never leaves the machine
Proves possession, not identity	The CN is a real name you can write rules about
Both sides share one secret	Each side has its own private key
Rotation needs a coordinated deploy	Certificates are reissued per service, independently
Leaks into logs and config	There is no secret string to paste anywhere

Error	Meaning	Fix
`x509: certificate specifies an incompatible key usage`	The certificate lacks `clientAuth`	Add it to `gen-certs.sh` and rerun the script
`tls: client didn't provide a certificate`	Working as intended: the caller sent none	Pass `--cert` and `--key` to curl
`bad certificate` (alert 42)	The peer's certificate was rejected	Both sides must trust the same `ca.crt`
Go panics on `PeerCertificates[0]`	`ClientAuth` is not `RequireAndVerifyClientCert`	Set it, so a certificate is guaranteed
Node accepts callers with no certificate	You set `requestCert` but not `rejectUnauthorized`	Always set both

Mutual TLS - Both Sides Prove Who They Are

Learning objectives

The one-word change

Mutual TLS - Both Sides Prove Who They Are

Learning objectives

The one-word change

Why a certificate beats a password

What changes in the handshake

Regenerate the certificates for both roles

Go: one config for both directions

Build the TLS config

Read the caller's name in Go

Present our certificate from Go

Wire it up

The complete Go file

TypeScript: the same

Require a certificate back

Read the caller's name in Node

Present our certificate from Node

Log rejected handshakes

The complete TypeScript file

Run it and see the difference

Test 1: no certificate

Test 2: with a certificate

Two rules to take to work

Rule 1: headers are claims, TLS is proof

Rule 2: failing early is a feature

Score card

The gap certificates cannot close

Common errors

Lesson 7 checkpoint