​

Certificate Authority overview

• mTLS between internal services — every service gets a leaf, every TLS handshake authenticates both ends.
• Service identity — short-lived certs are a stronger identity than long-lived API keys (a stolen cert dies on its own).
• IoT / device fleets — issue a leaf per device, scope it via roles.
• Replacing manual certificate operations — no more long-lived self-signed .pem files in git.

​

The trust chain at a glance

Root CA (10 years)
   └── Intermediate CA (auto-rotated, e.g. 30 days)
        ├── Leaf cert  api.example.com   (e.g. 30 days)
        ├── Leaf cert  worker.example.com
        └── Leaf cert  iot-device-7af2

• Root — long-lived (10 years by default). Signs only intermediates. Its private key is wrapped with your tenant master key, so cryptographic erasure of that master key permanently destroys the root.
• Intermediate — short-lived. KnoxCall’s lease manager auto-rotates it before expiry. There’s only ever one active intermediate per root at a time.
• Leaf — issued under a role that constrains what it can claim (allowed domains, max TTL, etc).

​

Customer-facing flow

1. Create a root in the admin UI under Certificate Authority → New Root. Pick a mount name (corp, iot, web) and the Subject DN fields. KnoxCall auto-creates the first intermediate.
2. Define a role that scopes what leaves can be issued under this root — e.g. “only *.internal.example.com, max TTL 7 days”.
3. Issue a leaf with POST /admin/pki/roots/{name}/issue/{role}. You get back the cert PEM + private key — the private key is shown once and never stored.
4. Install the root cert in clients’ trust stores (GET /admin/pki/roots/{name}/cert returns the PEM).
5. Revoke any leaf if it leaks (POST /admin/pki/roots/{name}/revoke). The cert lands in the CRL.

​

What’s stored

​

Algorithms

• v1: ECDSA P-256 only (root, intermediate, and leaf).
• Roadmap: RSA, EdDSA. The schema’s key_algorithm column is enum-constrained so adding new algorithms is a server change, not a data migration.

​

Issuance roles

• allowed_domains — glob list of CN/SAN values, e.g. ['*.example.com', 'api.internal'].
• allow_subdomains — whether foo.example.com is allowed when the role allows example.com.
• allow_wildcards — whether the leaf itself can be a wildcard cert.
• max_ttl_seconds / default_ttl_seconds — TTL bounds. Leaves are also capped at the intermediate’s remaining validity, so a leaf can’t outlive the intermediate that signed it.

​

Issuance paths

​

Revocation & CRLs

• POST /admin/pki/roots/{name}/revoke with a serial_hex flips the cert’s revoked_at timestamp.
• GET /admin/pki/roots/{name}/crl returns a Certificate Revocation List your verifiers can poll.
• v1 emits a text CRL for inspection; binary DER CRL is a follow-up. Don’t depend on the byte format yet for production verifiers.
• Short TTLs (days, not years) mean revocation is mostly a “fast kill” tool — most leaves age out on their own before a CRL pull would catch them.

​

Lease integration

​

Next steps

• Roles & issuance →
• Tenant master key → — what cryptographic erasure of a tenant master key does to your CA
• API reference →