Lesson 12 of 15 · 40 min

Build the Identity Library

Write the small amount of shared code that every program needs to fetch a short-lived identity, verify a peer by SPIFFE ID rather than hostname, and keep rotating without a restart.

Learning objectives

Fetch an identity over a unix socket without sending any credential.
Replace hostname verification with this course's SPIFFE ID profile — one URI SAN, a trusted chain, the peer's role, and an allow list.
Explain why the identity is read through a callback instead of stored as a value.
Share one identity implementation across three Go programs and one Node service.

What this lesson is for

Lesson 11 built the agent that hands out sixty-second certificates. Nothing uses it yet.

Still true after this lesson	Why it does not change
Mutual TLS, both sides prove themselves	Lesson 7's idea is untouched. Only where the certificate comes from changes
The handshake proves possession by signing	Same protocol, same messages, same guarantees
Trust means "signed by a CA I chose"	Still true. The CA now lives in memory instead of a file
The six token checks	`token.go` is not edited at all in this lesson
Tokens carry the user, certificates carry the service	Unchanged. Only the format of the service name changes
Ports 8443, 8444, 8445	Unchanged

spiffe/spiffe.goGo

// Identity is one short-lived certificate plus the CAs we currently trust.
type Identity struct {
	Cert   tls.Certificate
	Bundle *x509.CertPool
	ID     string
	Expiry time.Time
}

// Source holds the identity in use right now and swaps it on rotation.
type Source struct {
	current atomic.Pointer[Identity]
}

// New fetches the first identity. It fails if the workload API is not running.
func New() (*Source, error) {
	id, err := fetch()
	if err != nil {
		return nil, err
	}
	s := &Source{}
	s.current.Store(id)
	return s, nil
}

// Current is the identity to use for the next connection.
func (s *Source) Current() *Identity { return s.current.Load() }

spiffe/spiffe.goGo

// fetch asks the workload API for an identity.
//
// We send nothing: no key, no password, no token. The agent works out who we
// are by inspecting our process. That is how the secret zero problem
// disappears -- there is no first secret to hand out.
func fetch() (*Identity, error) {
	conn, err := net.Dial("unix", SocketPath)
	if err != nil {
		return nil, err
	}
	defer conn.Close()

	var s svidJSON
	if err := json.NewDecoder(conn).Decode(&s); err != nil {
		return nil, fmt.Errorf("workload api gave no identity: %w", err)
	}

	cert, err := tls.X509KeyPair([]byte(s.Cert), []byte(s.Key))
	if err != nil {
		return nil, err
	}
	leaf, err := x509.ParseCertificate(cert.Certificate[0])
	if err != nil {
		return nil, err
	}
	pool := x509.NewCertPool()
	if !pool.AppendCertsFromPEM([]byte(s.Bundle)) {
		return nil, errors.New("trust bundle is empty")
	}

	return &Identity{Cert: cert, Bundle: pool, ID: s.SpiffeID, Expiry: leaf.NotAfter}, nil
}

spiffe/spiffe.goGo

func (s *Source) verify(allowed []string, peerRole x509.ExtKeyUsage) func([][]byte, [][]*x509.Certificate) error {
	return func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
		if len(rawCerts) == 0 {
			return errors.New("peer sent no certificate")
		}
		peer, err := x509.ParseCertificate(rawCerts[0])
		if err != nil {
			return err
		}

		// Everything after the leaf is an intermediate. Our demo CA signs
		// leaves directly, so this is empty here -- but real deployments have
		// intermediates, and a verifier that ignores them rejects valid chains.
		intermediates := x509.NewCertPool()
		for _, raw := range rawCerts[1:] {
			ca, parseErr := x509.ParseCertificate(raw)
			if parseErr != nil {
				return fmt.Errorf("unparsable intermediate: %w", parseErr)
			}
			intermediates.AddCert(ca)
		}

		// Step 1: is it signed by a CA in our current trust bundle?
		if _, err := peer.Verify(x509.VerifyOptions{
			Roots:         s.Current().Bundle,
			Intermediates: intermediates,
			// Check the role the PEER is playing, not "any purpose". When we
			// are the server the peer is a client; when we call out it is a
			// server. ExtKeyUsageAny would accept a certificate issued for the
			// opposite direction.
			KeyUsages: []x509.ExtKeyUsage{peerRole},
		}); err != nil {
			return fmt.Errorf("untrusted certificate: %w", err)
		}
		// Step 2: is this shaped like a leaf SVID at all? Verify above proves the signature
		// chain. It does NOT prove the peer sent a leaf: Go applies its CA
		// rules to issuers, not to the certificate being checked, so a CA
		// certificate presented as a client certificate passes unchallenged.
		// The X.509-SVID profile closes that door, so we enforce it here.
		// IsCA is also false when the basicConstraints extension is missing,
		// so test that the extension was present before reading its value.
		if !peer.BasicConstraintsValid {
			return errors.New("leaf SVID has no basicConstraints extension")
		}
		if peer.IsCA {
			return errors.New("leaf SVID has CA:TRUE")
		}
		if peer.KeyUsage&x509.KeyUsageDigitalSignature == 0 {
			return errors.New("leaf SVID does not set digitalSignature")
		}
		if peer.KeyUsage&(x509.KeyUsageCertSign|x509.KeyUsageCRLSign) != 0 {
			return errors.New("leaf SVID sets a signing key usage")
		}

		// Step 3: is the SPIFFE ID inside it one we allow?
		//
		// The SPIFFE specification is explicit: an X.509-SVID MUST contain
		// exactly one URI SAN, and a validator MUST reject anything with more.
		// Matching "any URI in the list" would let one certificate pass as one
		// identity and then be read as another.
		if len(peer.URIs) != 1 {
			return fmt.Errorf("an X.509-SVID must have exactly one URI SAN, got %d", len(peer.URIs))
		}
		id := peer.URIs[0].String()
		if !slices.Contains(allowed, id) {
			return fmt.Errorf("peer is %s, expected one of %v", id, allowed)
		}
		return nil
	}
}

spiffe/spiffe.goGo

// ServerTLS accepts connections from the listed identities and nobody else.
func (s *Source) ServerTLS(allowed ...string) *tls.Config {
	return &tls.Config{
		GetCertificate: func(*tls.ClientHelloInfo) (*tls.Certificate, error) {
			return &s.Current().Cert, nil
		},
		ClientAuth:            tls.RequireAnyClientCert,
		VerifyPeerCertificate: s.verify(allowed, x509.ExtKeyUsageClientAuth),
		MinVersion:            tls.VersionTLS13,
	}
}

// ClientTLS connects only to the identity given.
func (s *Source) ClientTLS(expected string) *tls.Config {
	return &tls.Config{
		GetClientCertificate: func(*tls.CertificateRequestInfo) (*tls.Certificate, error) {
			return &s.Current().Cert, nil
		},
		InsecureSkipVerify:    true,
		VerifyPeerCertificate: s.verify([]string{expected}, x509.ExtKeyUsageServerAuth),
		MinVersion:            tls.VersionTLS13,
	}
}

spiffe/spiffe.goGo

// KeepFresh replaces the identity forever, on a timer.
func (s *Source) KeepFresh(every time.Duration, report func(*Identity, error)) {
	for {
		time.Sleep(every)
		id, err := fetch()
		if err != nil {
			// The old identity is still valid for a while, so this is survivable.
			report(nil, err)
			continue
		}
		s.current.Store(id)
		report(id, nil)
	}
}

// PeerID pulls the SPIFFE ID off a certificate the handshake already verified.
func PeerID(cert *x509.Certificate) (string, error) {
	if len(cert.URIs) != 1 {
		return "", fmt.Errorf("expected exactly one URI SAN, got %d", len(cert.URIs))
	}
	return cert.URIs[0].String(), nil
}

spiffe/spiffe.goGo

// Package spiffe holds the parts every program in this project needs:
// fetching a short-lived identity, keeping it fresh, and checking who the
// peer is. The two services and the auth server all import it.
package spiffe

import (
	"crypto/tls"
	"crypto/x509"
	"encoding/json"
	"errors"
	"fmt"
	"net"
	"slices"
	"sync/atomic"
	"time"
)

// SocketPath is where the workload API listens.
const SocketPath = "/tmp/spire-lite.sock"

// Every identity in this project -- certificates AND tokens -- is one of these.
const (
	GoID   = "spiffe://demo.local/service/go"
	TSID   = "spiffe://demo.local/service/typescript"
	AuthID = "spiffe://demo.local/service/auth"
)

// what the workload API sends back
type svidJSON struct {
	SpiffeID string `json:"spiffe_id"`
	Cert     string `json:"cert"`
	Key      string `json:"key"`
	Bundle   string `json:"bundle"`
}

// Identity is one short-lived certificate plus the CAs we currently trust.
type Identity struct {
	Cert   tls.Certificate
	Bundle *x509.CertPool
	ID     string
	Expiry time.Time
}

// Source holds the identity in use right now and swaps it on rotation.
type Source struct {
	current atomic.Pointer[Identity]
}

// New fetches the first identity. It fails if the workload API is not running.
func New() (*Source, error) {
	id, err := fetch()
	if err != nil {
		return nil, err
	}
	s := &Source{}
	s.current.Store(id)
	return s, nil
}

// Current is the identity to use for the next connection.
func (s *Source) Current() *Identity { return s.current.Load() }

// fetch asks the workload API for an identity.
//
// We send nothing: no key, no password, no token. The agent works out who we
// are by inspecting our process, so there is no first secret to hand out.
func fetch() (*Identity, error) {
	conn, err := net.Dial("unix", SocketPath)
	if err != nil {
		return nil, err
	}
	defer conn.Close()

	var s svidJSON
	if err := json.NewDecoder(conn).Decode(&s); err != nil {
		return nil, fmt.Errorf("workload api gave no identity: %w", err)
	}

	cert, err := tls.X509KeyPair([]byte(s.Cert), []byte(s.Key))
	if err != nil {
		return nil, err
	}
	leaf, err := x509.ParseCertificate(cert.Certificate[0])
	if err != nil {
		return nil, err
	}
	pool := x509.NewCertPool()
	if !pool.AppendCertsFromPEM([]byte(s.Bundle)) {
		return nil, errors.New("trust bundle is empty")
	}

	return &Identity{Cert: cert, Bundle: pool, ID: s.SpiffeID, Expiry: leaf.NotAfter}, nil
}

// KeepFresh replaces the identity forever, on a timer. Certificates live 60
// seconds; call this with something well under that.
func (s *Source) KeepFresh(every time.Duration, report func(*Identity, error)) {
	for {
		time.Sleep(every)
		id, err := fetch()
		if err != nil {
			// The old identity is still valid for a while, so this is survivable.
			report(nil, err)
			continue
		}
		s.current.Store(id)
		report(id, nil)
	}
}

// verify replaces hostname checking with SPIFFE ID checking.
func (s *Source) verify(allowed []string, peerRole x509.ExtKeyUsage) func([][]byte, [][]*x509.Certificate) error {
	return func(rawCerts [][]byte, _ [][]*x509.Certificate) error {
		if len(rawCerts) == 0 {
			return errors.New("peer sent no certificate")
		}
		peer, err := x509.ParseCertificate(rawCerts[0])
		if err != nil {
			return err
		}

		// Everything after the leaf is an intermediate. Our demo CA signs
		// leaves directly, so this is empty here -- but real deployments have
		// intermediates, and a verifier that ignores them rejects valid chains.
		intermediates := x509.NewCertPool()
		for _, raw := range rawCerts[1:] {
			ca, parseErr := x509.ParseCertificate(raw)
			if parseErr != nil {
				return fmt.Errorf("unparsable intermediate: %w", parseErr)
			}
			intermediates.AddCert(ca)
		}

		if _, err := peer.Verify(x509.VerifyOptions{
			Roots:         s.Current().Bundle,
			Intermediates: intermediates,
			// Check the role the PEER is playing, not "any purpose". When we
			// are the server the peer is a client; when we call out it is a
			// server. ExtKeyUsageAny would accept a certificate issued for the
			// opposite direction.
			KeyUsages: []x509.ExtKeyUsage{peerRole},
		}); err != nil {
			return fmt.Errorf("untrusted certificate: %w", err)
		}
		// Is this shaped like a leaf SVID at all? Verify above proves the signature
		// chain. It does NOT prove the peer sent a leaf: Go applies its CA
		// rules to issuers, not to the certificate being checked, so a CA
		// certificate presented as a client certificate passes unchallenged.
		// The X.509-SVID profile closes that door, so we enforce it here.
		// IsCA is also false when the basicConstraints extension is missing,
		// so test that the extension was present before reading its value.
		if !peer.BasicConstraintsValid {
			return errors.New("leaf SVID has no basicConstraints extension")
		}
		if peer.IsCA {
			return errors.New("leaf SVID has CA:TRUE")
		}
		if peer.KeyUsage&x509.KeyUsageDigitalSignature == 0 {
			return errors.New("leaf SVID does not set digitalSignature")
		}
		if peer.KeyUsage&(x509.KeyUsageCertSign|x509.KeyUsageCRLSign) != 0 {
			return errors.New("leaf SVID sets a signing key usage")
		}

		// The SPIFFE specification is explicit: an X.509-SVID MUST contain
		// exactly one URI SAN, and a validator MUST reject anything with more.
		// Matching "any URI in the list" would let one certificate pass as one
		// identity and then be read as another.
		if len(peer.URIs) != 1 {
			return fmt.Errorf("an X.509-SVID must have exactly one URI SAN, got %d", len(peer.URIs))
		}
		id := peer.URIs[0].String()
		if !slices.Contains(allowed, id) {
			return fmt.Errorf("peer is %s, expected one of %v", id, allowed)
		}
		return nil
	}
}

// ServerTLS accepts connections from the listed identities and nobody else.
func (s *Source) ServerTLS(allowed ...string) *tls.Config {
	return &tls.Config{
		GetCertificate: func(*tls.ClientHelloInfo) (*tls.Certificate, error) {
			return &s.Current().Cert, nil
		},
		// Demand a certificate, but do the checking ourselves: we need the
		// SPIFFE ID allow-list and the leaf profile, and we need the trust
		// bundle read fresh on every handshake rather than pinned at config
		// time. (A server never hostname-checks a client certificate.)
		ClientAuth:            tls.RequireAnyClientCert,
		VerifyPeerCertificate: s.verify(allowed, x509.ExtKeyUsageClientAuth),
		MinVersion:            tls.VersionTLS13,
	}
}

// ClientTLS connects only to the identity given.
func (s *Source) ClientTLS(expected string) *tls.Config {
	return &tls.Config{
		GetClientCertificate: func(*tls.CertificateRequestInfo) (*tls.Certificate, error) {
			return &s.Current().Cert, nil
		},
		// InsecureSkipVerify switches off BOTH built-in checks: the signature
		// chain and the hostname. On its own that accepts any certificate at
		// all, and it is a real bug in most code that contains it. It is
		// survivable here only because VerifyPeerCertificate below redoes both
		// -- chain against the current bundle, then SPIFFE ID and leaf profile
		// -- and still drops the connection on failure.
		InsecureSkipVerify:    true,
		VerifyPeerCertificate: s.verify([]string{expected}, x509.ExtKeyUsageServerAuth),
		MinVersion:            tls.VersionTLS13,
	}
}

// PeerID pulls the SPIFFE ID off a certificate the handshake already verified.
func PeerID(cert *x509.Certificate) (string, error) {
	if len(cert.URIs) != 1 {
		return "", fmt.Errorf("expected exactly one URI SAN, got %d", len(cert.URIs))
	}
	return cert.URIs[0].String(), nil
}

spiffe.tsTypeScript

// The SPIFFE half of the TypeScript service: fetch a short-lived identity,
// read its expiry, and check who the peer is.

import { createConnection } from "node:net";
import { X509Certificate } from "node:crypto";
import type { PeerCertificate } from "node:tls";

export const SOCKET_PATH = "/tmp/spire-lite.sock";

// Every identity in this project -- certificates AND tokens -- is one of these.
export const GO_ID = "spiffe://demo.local/service/go";
export const TS_ID = "spiffe://demo.local/service/typescript";
export const AUTH_ID = "spiffe://demo.local/service/auth";

export type Svid = {
  spiffe_id: string;
  cert: string;
  key: string;
  bundle: string;
};

/**
 * Ask the workload API for an identity.
 *
 * We send nothing: no key, no password, no token. The agent works out who we
 * are by inspecting our process, so there is no first secret to hand out.
 */
export function fetchSvid(): Promise<Svid> {
  return new Promise((resolve, reject) => {
    const socket = createConnection({ path: SOCKET_PATH });
    let data = "";
    socket.on("data", (chunk) => (data += chunk));
    socket.on("end", () => {
      try {
        resolve(JSON.parse(data));
      } catch {
        reject(new Error("workload api gave no identity"));
      }
    });
    socket.on("error", reject);
  });
}

/** When does this certificate expire? Read straight out of the PEM. */
export function expiryOf(svid: Svid): string {
  return new X509Certificate(svid.cert).validTo;
}

/**
 * Pull the URI SANs out of Node's certificate object.
 *
 * Node flattens the whole SAN extension into one display string, so this is
 * string handling, not X.509 parsing. It is adequate for enforcing "exactly
 * one URI SAN" in a course; a production service should read the DER with a
 * SPIFFE library rather than splitting a string meant for humans.
 */
function uriSans(cert: PeerCertificate): string[] {
  return (cert.subjectaltname ?? "")
    .split(", ")
    .filter((entry) => entry.startsWith("URI:"))
    .map((entry) => entry.slice("URI:".length));
}

/**
 * Check the peer's SPIFFE ID instead of its hostname.
 *
 * Node has already verified the signature chain against our trust bundle by
 * the time this runs; this is the identity half. Returning undefined means
 * "accepted", which is what Node's checkServerIdentity expects.
 */
export function checkSpiffeId(
  cert: PeerCertificate,
  allowed: string[],
): Error | undefined {
  // A leaf SVID must not be a CA certificate. Chain verification does not
  // check this for us: it applies CA rules to issuers, not to the certificate
  // being presented. Node exposes whether the certificate is a CA, so we can
  // reject CA:TRUE. It cannot tell cA:false from an omitted extension; the
  // callout below explains why this is still only a teaching validator.
  if (new X509Certificate(cert.raw).ca) {
    return new Error("leaf SVID has CA:TRUE");
  }

  const ids = uriSans(cert);
  // The SPIFFE specification requires exactly one URI SAN and requires
  // validators to reject anything with more. Two URIs would let a certificate
  // pass as one identity and be read as another.
  if (ids.length !== 1) {
    return new Error(`an X.509-SVID must have exactly one URI SAN, got ${ids.length}`);
  }
  if (!allowed.includes(ids[0])) {
    return new Error(`peer is '${ids[0]}', expected one of ${allowed}`);
  }
  return undefined;
}

/** The SPIFFE ID on a certificate that checkSpiffeId has already accepted. */
export function peerId(cert: PeerCertificate): string {
  const ids = uriSans(cert);
  if (ids.length !== 1) {
    throw new Error(`expected exactly one URI SAN, got ${ids.length}`);
  }
  return ids[0];
}

Build the Identity Library

Learning objectives

What this lesson is for

Build the Identity Library

Learning objectives

What this lesson is for

What stays exactly the same

The three new ideas

Idea 1: ask for an identity instead of loading one

Idea 2: check the name inside, not the address

Idea 3: read the identity through a callback, not a value

Step 1: the shared Go package

Identity and Source

Fetching

Verifying a peer

Why the leaf checks are not optional

The two configs

Rotation and peer identity

The complete spiffe package

Step 2: the shared TypeScript module

Lesson 12 checkpoint