mTLS & Certificate Management
Relevant source files
The following files were used as context for generating this wiki page:
mTLS (mutual TLS) and Certificate Management in Harbor Satellite provide a zero-trust security framework for communication between Ground Control and Satellites. This system ensures that both the client and server verify each other's identities using X.509 certificates before establishing a connection.
The project supports two primary modes for identity management: a standard file-based TLS approach with hot-reloading capabilities and a more advanced SPIFFE/SPIRE integration. The SPIFFE-based approach automates certificate issuance, rotation, and identity verification, which is recommended for production fleet-scale deployments.
Sources: QUICKSTART.md:27-46, deploy/quickstart/README.md:16-29
TLS Core Configuration
The system provides a centralized way to load and validate TLS configurations for both clients and servers. This logic is encapsulated in a dedicated TLS package that handles certificate loading, CA pool management, and validation.
TLS Config Structure
The Config structure defines the necessary parameters for establishing secure connections:
| Parameter | Type | Description |
|---|---|---|
| CertFile | string | Path to the X.509 certificate file |
| KeyFile | string | Path to the private key file |
| CAFile | string | Path to the CA certificate for verification |
| ServerName | string | Expected server name (SNI) |
| SkipVerify | bool | If true, skips certificate verification |
| MinVersion | uint16 | Minimum TLS version (Default: TLS 1.2) |
Sources: internal/tls/config.go:34-41, pkg/config/validate.go:146-154
Certificate Loading and Validation
The system includes utilities to parse PEM-encoded certificates and extract metadata such as expiry dates and Subject Alternative Names (SANs).
Sources: internal/tls/config.go:88-142
Certificate Hot-Reloading
Ground Control implements a CertWatcher middleware to enable zero-downtime certificate updates. This component monitors the filesystem for modifications to certificate files and reloads them dynamically without requiring a server restart.
CertWatcher Workflow
The CertWatcher uses a background goroutine and a ticker to periodically check the ModTime of the certificate and key files.
- Initialization: Loads the initial certificate and records the last modification time.
- Monitoring: A ticker (defaulting to 30 seconds in the server) triggers a check.
- Reload: If
os.Statshows a newer modification time,tls.LoadX509KeyPairis called to update the internal certificate reference. - Serving: Implements
GetCertificateandGetClientCertificatemethods fortls.Configto provide the most recent certificate to new connections.
Sources: ground-control/internal/middleware/certwatcher.go:13-90, ground-control/internal/server/server.go:189-204
SPIFFE/SPIRE Integration
For high-security environments, Harbor Satellite integrates with SPIFFE (Secure Production Identity Framework for Everyone) and SPIRE (the SPIFFE Runtime Environment). This replaces manual certificate management with automated, short-lived SVIDs (SPIFFE Verifiable Identity Documents).
Architecture
Communication is secured via mTLS using identities issued by a central SPIRE Server.
Attestation Methods
Before receiving an identity, components must attest themselves to the SPIRE server using one of the following methods:
| Method | Description | Source File |
|---|---|---|
| Join Token | A one-time token generated by the server for initial bootstrap. | deploy/quickstart/README.md:11 |
| X.509 PoP | Proof-of-Possession of a pre-provisioned certificate signed by a trusted CA. | deploy/quickstart/spiffe/x509pop/README.md:3 |
| SSH PoP | Uses SSH host certificates for node attestation. | deploy/quickstart/README.md:13 |
Automated Certificate Generation (X.509 PoP)
The project provides scripts to generate the necessary PKI hierarchy for X.509 PoP attestation, including:
- Upstream Authority CA: The root of trust for the SPIRE server.
- X.509 PoP CA: An intermediate CA used specifically to sign agent certificates.
- Agent Certificates: Leaf certificates for Ground Control and Satellite agents, including SPIFFE ID SANs (e.g.,
spiffe://harbor-satellite.local/agent/ground-control).
Sources: deploy/quickstart/spiffe/x509pop/external/gc/generate-certs.sh:19-68
Server-Side mTLS Implementation
In ground-control, the server configuration prioritizes SPIFFE identities if enabled. If SPIFFE is disabled, it falls back to standard TLS with optional client certificate verification for mTLS.
Server TLS Logic
When file-based mTLS is used, the server requires a CAFile. The CA is loaded into a CertPool and assigned to tls.Config.ClientCAs, with tls.Config.ClientAuth set to tls.RequireAndVerifyClientCert.
Sources: ground-control/internal/server/server.go:174-206, internal/tls/config.go:68-85
Summary
Harbor Satellite ensures secure edge-to-cloud communication through robust mTLS and certificate management. By supporting both dynamic file-based TLS with the CertWatcher and automated zero-trust identities via SPIFFE/SPIRE, the system provides flexibility for various deployment scales while maintaining a high security posture.