Gestion des certificats TLS

Certificats TLS 1.3 du gRPC entre agents et Hub. Mode auto (CA générée toute seule) et mode custom avec votre PKI.

Sur le port gRPC (50051), tout le trafic agent ↔ Hub passe en TLS 1.3. Deux modes : auto (défaut) et custom.

Mode auto (défaut)

Avec TLS_MODE=auto, le Hub fabrique au premier démarrage une autorité de certification auto-signée et un certificat serveur. Ils vivent dans le volume Docker pki_data et sont réutilisés ensuite.

pki_data/
├── ca.pem       # CA certificate, sent to agents at registration
├── ca.key       # CA private key
├── server.pem   # Server certificate, signed by the CA
└── server.key   # Server private key

Les deux certificats sont en ECDSA P-256.

Certificat	CN	Validité
CA	`watchflare CA`	10 ans
Serveur	`watchflare`	5 ans

À l’enregistrement, le Hub envoie la CA à l’agent. L’agent la fige pour la suite : rien à copier à la main. Sous Linux : /etc/watchflare/ca.pem. Sous macOS : $(brew --prefix)/etc/watchflare/ca.pem.

Attention

En mode auto, CA et certificat serveur sont toujours régénérés ensemble. Impossible de renouveler le serveur tout seul. Si vous supprimez server.pem pour forcer un renouvellement, la CA change aussi : il faut réenrôler tous les agents.

Mode custom

TLS_MODE=custom : le Hub prend vos certificats. Utile si vous avez déjà une PKI interne.

Ajoutez ces variables au .env :

TLS_MODE=custom
TLS_CERT_FILE=/certs/server.pem
TLS_KEY_FILE=/certs/server.key
TLS_CA_FILE=/certs/ca.pem

Montez le dossier de certificats dans le conteneur Hub :

services:
  watchflare:
    volumes:
      - pki_data:/var/lib/watchflare/pki
      - /etc/ssl/watchflare:/certs:ro

Contraintes

TLS_CA_FILE doit être la CA qui a signé TLS_CERT_FILE. C’est cette CA que les agents reçoivent à l’enregistrement et qu’ils figent.
TLS 1.3 est obligatoire. En dessous, le Hub coupe, quel que soit le mode.
Le certificat serveur n’a pas à porter le nom d’hôte du Hub. En revanche, server_name dans agent.conf (défaut : watchflare) doit figurer dans les SAN DNS — Go vérifie les SAN, pas le CN. Un HostSNI("*") sur le reverse proxy évite les décalages de nom. Voir Reverse proxy.

Attention

Si vous changez de CA après l’enrôlement, les agents refusent le nouveau certificat : ce n’est plus la CA qu’ils ont figée. Il faudra réenrôler chaque machine concernée.

Inspecter les certificats

Depuis l’intérieur du conteneur, pour ceux générés en mode auto :

docker exec watchflare openssl x509 -in /var/lib/watchflare/pki/ca.pem -noout -text
docker exec watchflare openssl x509 -in /var/lib/watchflare/pki/server.pem -noout -text

Port gRPC et reverse proxies

Le port gRPC (50051) ne doit pas voir son TLS terminé par un reverse proxy. Les agents ont figé la CA du Hub : un certificat d’une autre CA est rejeté. Passez le proxy en passthrough TCP. Voir Reverse proxy.