Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Certificate Authority overview

KnoxCall’s Certificate Authority lets each tenant run a private PKI: a long-lived root signs short-lived intermediates, and the intermediate signs leaf certificates you hand out to services. You get a clean trust chain you control without standing up step-ca, cfssl, or Vault PKI yourself. Use it for:
  • 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).
You install the root in your trust store once. Everything below it validates automatically.

​
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

ObjectStoredPrivate key location
RootCert PEM + wrapped private keyKnoxCall, wrapped with tenant master key
IntermediateCert PEM + wrapped private keyKnoxCall (cloud) or shipped to self-hosted agents in the session bundle
LeafCert PEM onlyReturned to caller once, never persisted
If you lose a leaf’s private key, you re-issue. KnoxCall doesn’t have it.

​
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

A role is the constraint template applied when a leaf is issued under it. The Vault equivalent is pki/roles/<name>.
  • 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.
See Roles & issuance for the rule matrix.

​
Issuance paths

PathWhere SQL/signing runsWhen to use
Cloud (issued_via='cloud')KnoxCall control plane signs the leafDefault. Customers using cloud KnoxCall.
Agent (issued_via='agent')A self-hosted KnoxCall agent signs the leaf locally using the intermediate’s private key in its session bundleSelf-hosted deployments where the issuance call must stay inside the customer’s network.
Both paths produce certs under the same root chain — clients in your trust store don’t know or care which one signed.

​
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

The intermediate is rotated by the lease manager via the pki_intermediate lease type. You don’t run a cron — KnoxCall mints the next intermediate before the current one expires, retires the old one, and (for self-hosted) ships the new one to agents in their next session bundle. If an intermediate ever expires without a successor, leaf issuance fails with a clear error. Inspect the Active leases panel on the Certificate Authority page to see when the next rotation will happen.

​
Next steps