> ## 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

> Run a private CA inside KnoxCall. Issue short-lived TLS certs for mTLS, internal services, and IoT — without standing up your own PKI.

# 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

```text theme={"dark"}
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](/essentials/key-management/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](#revocation--crls).

## What's stored

| Object       | Stored                         | Private key location                                                    |
| ------------ | ------------------------------ | ----------------------------------------------------------------------- |
| Root         | Cert PEM + wrapped private key | KnoxCall, wrapped with tenant master key                                |
| Intermediate | Cert PEM + wrapped private key | KnoxCall (cloud) or shipped to self-hosted agents in the session bundle |
| Leaf         | Cert PEM only                  | **Returned 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](/essentials/pki/roles-and-issuance) for the rule matrix.

## Issuance paths

| Path                             | Where SQL/signing runs                                                                                         | When to use                                                                              |
| -------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Cloud** (`issued_via='cloud'`) | KnoxCall control plane signs the leaf                                                                          | Default. 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 bundle | Self-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](/essentials/databases/leases) 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

* [Roles & issuance →](/essentials/pki/roles-and-issuance)
* [Tenant master key →](/essentials/key-management/tenant-master-key) — what cryptographic erasure of a tenant master key does to your CA
* [API reference →](/api-reference/overview)