Certificate Management

Generate and manage TLS certificates and JWT signing keys for the Umoo platform.

Overview

The umoo cert CLI commands handle PKI operations:

• TLS certificates — self-signed CA + server certificates, or ACME-issued certificates (Let's Encrypt, ZeroSSL)
• JWT keys — RSA key pairs for signing and verifying JWT tokens
• Certificate renewal — automated renewal of self-signed certificates before expiry

TLS Certificate Generation

Self-Signed Mode

Generate a private CA and server certificate:

umoo cert tls generate --mode selfsigned \
  --domain umoo.yun \
  --output-dir ./configs/pki

This produces four files:

File	Description
ca.crt	CA certificate (distribute to clients for trust)
ca.key	CA private key (keep secure)
server.crt	Server certificate signed by the CA
server.key	Server private key

Options

Flag	Default	Description
--domain	localhost	Domain/CN for the certificate
--sans	—	Additional SANs, comma-separated (DNS names or IPs)
--validity	365d	Server certificate validity period
--ca-validity	3650d	CA certificate validity period
--output-dir	./configs/pki	Output directory
--force	false	Overwrite existing certificates

Example with SANs

umoo cert tls generate --mode selfsigned \
  --domain umoo.yun \
  --sans "umoo.internal,10.0.0.1,*.umoo.yun" \
  --validity 730d \
  --output-dir /etc/umoo/pki

ACME Mode (Let's Encrypt)

Obtain a certificate from an ACME provider:

umoo cert tls generate --mode acme \
  --domain umoo.yun \
  --email admin@example.com \
  --output-dir ./configs/pki

This produces:

File	Description
server.crt	Server certificate from the ACME provider
server.key	Server private key

ACME Options

Flag	Default	Description
--provider	letsencrypt	ACME provider preset or directory URL
--email	—	Account email (required)
--staging	false	Use the staging endpoint (for testing)
--challenge	http	Challenge type: http or dns
--http-port	:80	Port for HTTP-01 challenge listener
--dns-provider	—	DNS provider for DNS-01 challenge (e.g. cloudflare)

DNS-01 Challenge (Cloudflare)

For wildcard certificates or when port 80 is unavailable:

export CF_API_TOKEN=your_cloudflare_api_token

umoo cert tls generate --mode acme \
  --domain "*.umoo.yun" \
  --email admin@example.com \
  --challenge dns \
  --dns-provider cloudflare

TLS Certificate Renewal

Renew self-signed certificates before expiry:

umoo cert tls renew --output-dir ./configs/pki

The command checks whether the existing certificate is within the renewal window. If so, it regenerates the server certificate using the existing CA.

Flag	Default	Description
--output-dir	./configs/pki	Directory containing cert files
--force	false	Renew even if not near expiry
--renew-before	30d	Renewal threshold (renew if expiry is within this period)

Automated Renewal

Set up a cron job or systemd timer:

# Renew daily, only acts if within 30 days of expiry
0 3 * * * /usr/local/bin/umoo cert tls renew --output-dir /etc/umoo/pki

Certificate Inspection

View details of an existing certificate:

# Inspect default server cert
umoo cert tls info --output-dir ./configs/pki

# Inspect a specific certificate file
umoo cert tls info /path/to/cert.pem

Output includes: subject, issuer, SANs, validity period, serial number, and key usage.

JWT Key Generation

Generate an RSA key pair for JWT token signing:

umoo cert jwt generate --output-dir ./configs/jwt

This produces:

File	Description
private.key	RSA private key for signing JWTs
public.key	RSA public key for verifying JWTs

Flag	Default	Description
--output-dir	./configs/jwt	Output directory
--key-size	2048	RSA key size in bits
--force	false	Overwrite existing keys

Configure the server to use these keys:

jwt:
  private_key: ./configs/jwt/private.key
  public_key: ./configs/jwt/public.key

Device Certificates

Devices authenticate to the platform using mTLS client certificates. The certificate lifecycle:

1. An admin generates a claim token for a device.
2. The device agent connects with the claim token and submits a CSR (Certificate Signing Request).
3. The platform CA signs the CSR and returns the device certificate.
4. The agent uses the certificate for all subsequent mTLS connections.

Device certificates are managed automatically — no manual intervention is needed after the initial claim.

Security Best Practices

• Store CA private keys (ca.key) and JWT private keys (private.key) with restricted file permissions (chmod 600).
• Use ACME mode in production for publicly-trusted certificates.
• Set up automated certificate renewal to avoid service interruptions.
• Use a key size of at least 2048 bits for RSA keys (4096 recommended for high-security environments).
• Rotate JWT keys periodically by generating new keys and updating the server configuration.