Mutual TLS (mTLS) Authentication

Overview

Mutual TLS provides bidirectional authentication where both the backend server and CapyDaemon verify each other's identities using X.509 certificates before establishing a connection.

Pros

• Strong bidirectional authentication: Both the backend API and CapyDaemon will verify each other's identities, preventing unauthorized hosts from connecting to the backend and preventing CapyDaemon from connecting to rogue servers
• Addresses primary threat: Directly mitigates the risk of attackers impersonating the backend server to issue malicious tasks to managed hosts
• Built-in encryption: All API communication (task dispatch, status updates, config file pulls) is encrypted by default
• No credential exposure: Unlike API keys or tokens, certificates are harder to extract and reuse, and compromised certificates can be revoked via CRL/OCSP
• Well-suited for pull model: Since CapyDaemon initiates all connections, mTLS seamlessly authenticates outbound requests without additional complexity
• Cross-platform compatibility: Go's crypto/tls package works consistently across Linux, Windows, macOS, and BSD, simplifying multi-OS support
• Scales well: Once PKI infrastructure is established, adding new hosts (10 → 100+) is primarily a matter of certificate generation and distribution

Cons

• Certificate management complexity: Requires PKI infrastructure to issue, renew, and revoke certificates for each monitored host
  • Initial setup: Certificate authority (CA) setup, certificate generation for backend + all CapyDaemon instances
  • Ongoing: Certificate rotation before expiry (typically 1-2 years), revocation handling for compromised/decommissioned hosts
  • At scale (100+ hosts): Manual certificate management becomes impractical; will need automation tooling
• Deployment overhead: Each new monitored host requires certificate provisioning before CapyDaemon can connect
  • For <10 hosts: manageable with scripts
  • For 100+ hosts: requires automated provisioning (consider tools like cert-manager, Vault, or custom automation)
• Troubleshooting complexity: Certificate validation errors can be cryptic; expired or misconfigured certificates will cause connection failures
  • Different error messages across Windows/Linux can complicate cross-platform troubleshooting
• Initial learning curve: Setting up a CA and understanding certificate chains requires upfront time investment
• Certificate distribution: Need secure method to distribute certificates to new hosts (especially important when scaling to homelab environment)

Implementation Ideas for different scale:

Capstone Proof-of-Concept (flat LAN, <10 hosts):

• Create simple CA using OpenSSL or Go's crypto package
• Script certificate generation for new hosts
• Store certificates alongside CapyDaemon binary on each host

Plan for a large homelab scale (~100 hosts):

• Automate certificate generation/distribution (scripted or tool-based)
• Implement certificate expiry monitoring and alerting
• Consider shorter-lived certificates (90 days) with automated renewal
• Document certificate troubleshooting for cross-platform issues

Far Future (or enterprise) considerations:

• Certificate revocation strategy for compromised/decommissioned hosts (CRL or OCSP)
• Secure bootstrap process for initial certificate distribution to new hosts
• Centralized certificate management if scaling beyond homelab