Skip to main content

Certificate Management

Sielum uses mutual TLS (mTLS) for all gRPC communication between agents and the server. Both sides authenticate with X.509 certificates signed by a shared CA.

Development certificates​

The quickest way to get started:

bash deploy/certs/gen-dev-certs.sh

This creates in deploy/certs/:

FilePurpose
ca.crtCA certificate (distributed to all agents)
ca.keyCA private key (never leave the server)
server.crtServer certificate (SAN: DNS:localhost,IP:127.0.0.1)
server.keyServer private key
agent.crtDefault agent certificate (for dev/testing only)
agent.keyDefault agent private key
warning

Dev certificates are self-signed and expire in 3 years. Never use them in production.

For production deployments, each agent device gets its own certificate via the enrollment API:

1. Enable enrollment on the server​

In deploy/.env.community:

ENROLLMENT_TOKEN=<secret-token>

In docker-compose.community.yml the backend must be started with --ca-key /etc/certs/ca.key to enable signing.

2. Enroll the agent​

sielum-agent enroll \
  --server https://your-sielum-server.example.com \
  --token  "$ENROLLMENT_TOKEN" \
  --out    /etc/sielum/certs/

The enrollment flow:

  1. Agent generates an ECDSA P-256 keypair locally
  2. Sends CSR + enrollment token to POST /api/enroll (HTTPS, no mTLS required for this endpoint)
  3. Server signs the CSR with the CA private key (validity: 2 years)
  4. Agent stores device.crt, device.key, ca.crt

Production certificate authorities​

For enterprise deployments, replace the dev CA with your corporate CA:

Using an enterprise CA​

  1. Generate a CSR for the server certificate with the appropriate SANs
  2. Have your CA team sign it
  3. Place the signed cert in deploy/certs/server.crt and the CA cert in deploy/certs/ca.crt
  4. For agent enrollment, configure the CA key or use pre-issued device certs

Using Let's Encrypt​

Let's Encrypt certificates can be used for the server's HTTPS/gRPC TLS, but not for mTLS client authentication. You still need a separate CA for agent certificates.

TLS configuration​

The server enforces:

  • TLS 1.3 minimum (TLS 1.2 is not accepted)
  • tls.RequireAndVerifyClientCert — connections without a valid client cert are rejected
  • No cipher suite restriction needed (TLS 1.3 has no weak ciphers)

These settings are hardcoded and cannot be downgraded via configuration.

Certificate rotation​

To rotate agent certificates:

  1. Run sielum-agent enroll again on the device — it generates a new keypair and obtains a fresh certificate
  2. The new cert is used on next agent restart
  3. Old certificates are automatically invalidated when the CA is rotated

To rotate the CA:

  1. Generate a new CA (openssl req -x509 -newkey ec -pkeyopt ec_paramgen_curve:P-256 ...)
  2. Re-enroll all agents
  3. Update deploy/certs/ca.crt and restart the server