# Aura PKI

Aura uses a small, self-contained X.509 PKI for **mutual authentication** of the inner
handshake. A single self-signed Aura **CA** issues one **server** certificate and one
**client** certificate per client. During the handshake the client verifies the server's
certificate and the server verifies the client's certificate, both against the CA.

The PKI is implemented in the `aura-pki` crate (`ca.rs`, `cert.rs`, `store.rs`) and exposed on
the command line as `aura pki ...` (`crates/aura-cli/src/pki.rs`,
`crates/aura-cli/src/main.rs`).

> The outer QUIC/TLS layer does **not** use this PKI — it accepts any certificate (see
> `protocol.md`, "Mimicry layer"). All certificate trust lives in the inner Aura handshake.

---

## Trust model

```
            Aura CA (self-signed)
            CN = <ca_name>, isCA, keyCertSign/crlSign
                     |
        +------------+------------+
        |                         |
   server leaf               client leaf(s)
   CN = <domain>             CN = <client_id>
   SAN: DNS:<domain>         (no SAN)
   EKU: serverAuth           EKU: clientAuth
```

- The **CA** is self-signed with `BasicConstraints: CA`, and key usages
  `keyCertSign` + `crlSign` + `digitalSignature`. Default lifetime **3650 days**.
- A **server leaf** carries `CN = <domain>`, a **`DNS:<domain>` SAN**, and
  `extendedKeyUsage = serverAuth`. The DNS SAN is what the client matches against its expected
  `server_name`.
- A **client leaf** carries `CN = <client_id>` and `extendedKeyUsage = clientAuth`. The CN is
  the identity the server learns and records as the session `peer_id`.
- Leaf key usages are `digitalSignature` + `keyEncipherment`. Default lifetime **365 days**.
- All issued certs (CA and leaves) backdate `not_before` by **5 minutes** to tolerate clock
  skew.

### Algorithms

All keys are **ECDSA P-256 / SHA-256** (rcgen's default `KeyPair::generate`). Private keys are
written in **PKCS#8 PEM**. Chain verification (in `cert.rs`) accepts ECDSA P-256/SHA-256
(required), and also ECDSA P-384/SHA-384 and Ed25519, so a deployment can switch key types
later without code changes.

---

## File layout

The CLI keeps files in plain directories. Conventional names
(`crates/aura-cli/src/pki.rs`):

| File          | Constant   | Contents                                  |
|---------------|------------|-------------------------------------------|
| `ca.crt`      | `CA_CERT`  | CA certificate (PEM)                      |
| `ca.key`      | `CA_KEY`   | CA private key (PKCS#8 PEM) — **secret**  |
| `server.crt`  |            | Server leaf certificate (PEM)             |
| `server.key`  |            | Server leaf private key (PEM) — **secret**|
| `client.crt`  |            | Client leaf certificate (PEM)             |
| `client.key`  |            | Client leaf private key (PEM) — **secret**|
| `revoked.crl` | `CRL_FILE` | Revocation list (one identifier per line) |

`issue-server` and `issue-client` load the CA from `ca.crt` + `ca.key` in the CA directory and
write `server.{crt,key}` / `client.{crt,key}` into the output directory. Paths beginning with
`~` are expanded to the home directory (from `$HOME`, or `$USERPROFILE` on Windows).

These names map directly onto the `[pki]` section of `server.toml` / `client.toml`
(`ca_cert`, `cert`, `key`).

---

## `aura pki` commands

```
aura pki init         --ca-name <CN>  --out <DIR>
aura pki issue-server --domain <DNS>  --out <DIR> [--ca <CA_DIR>]
aura pki issue-client --id <CLIENT>   --out <DIR> [--ca <CA_DIR>]
aura pki revoke       --id <ID>                   [--crl <PATH>]
aura pki list                                     [--crl <PATH>]
```

For `issue-server` / `issue-client`, `--ca` defaults to the value of `--out` (so the CA and
the issued leaf can live in the same directory). For `revoke` / `list`, `--crl` defaults to
`./revoked.crl`.

### `init` — create a CA

Generates a fresh self-signed CA and writes `ca.crt` + `ca.key` into `--out` (creating the
directory if needed).

```bash
aura pki init --ca-name "Aura Root CA" --out ~/.aura
# CA generated:
#   cert: ~/.aura/ca.crt
#   key:  ~/.aura/ca.key
```

### `issue-server` — issue a server certificate

Issues a server leaf for a DNS name, signed by the CA, with a `DNS:<domain>` SAN and
`serverAuth` EKU.

```bash
aura pki issue-server --domain vpn.example.com --out ~/.aura --ca ~/.aura
# server certificate issued for 'vpn.example.com':
#   cert: ~/.aura/server.crt
#   key:  ~/.aura/server.key
```

> The `--domain` must equal the name the client expects in the handshake. In the shipped
> client config that name is taken from `[client] sni`, so the camouflage SNI and the
> verified server SAN are the same value.

### `issue-client` — issue a client certificate

Issues a client leaf with `CN = <id>` and `clientAuth` EKU. The `<id>` becomes the verified
`peer_id` the server sees.

```bash
aura pki issue-client --id laptop --out ~/.aura --ca ~/.aura
# client certificate issued for 'laptop':
#   cert: ~/.aura/client.crt
#   key:  ~/.aura/client.key
```

### `revoke` — add to the revocation list

Adds an identifier — a **client id / Common Name** or a **certificate serial** (lowercase
hex, no separators) — to the CRL file, creating it (and parent directories) if absent.

```bash
aura pki revoke --id laptop --crl ~/.aura/revoked.crl
# revoked 'laptop' (CRL: ~/.aura/revoked.crl)
```

### `list` — show revoked identifiers

Prints the identifiers in the CRL file (empty if the file does not exist).

```bash
aura pki list --crl ~/.aura/revoked.crl
# revoked identifiers (CRL: ~/.aura/revoked.crl):
#   laptop
```

### End-to-end example

```bash
# 1. Create the CA.
aura pki init --ca-name "Aura Root CA" --out ~/.aura

# 2. Issue the server cert for its public DNS name.
aura pki issue-server --domain vpn.example.com --out ~/.aura

# 3. Issue a client cert per device.
aura pki issue-client --id laptop --out ~/.aura

# 4. (later) Revoke a compromised client.
aura pki revoke --id laptop
```

---

## Verification

Verification is performed by `AuraCertVerifier` (`crates/aura-pki/src/cert.rs`), built from
the CA certificate PEM. It uses **`rustls-webpki`** to validate the peer's leaf against the CA
trust anchor. The Aura handshake invokes it on each side (see `protocol.md`).

**Server certificate** (`verify_server_cert`), run by the client:

1. webpki chain verification against the CA with key usage **`serverAuth`**, plus validity
   (time) check.
2. The leaf must be valid for the requested `server_name` (DNS SAN match); a mismatch is
   `NameMismatch`.
3. CRL check (see below).

**Client certificate** (`verify_client_cert`), run by the server:

1. webpki chain verification against the CA with key usage **`clientAuth`**, plus validity.
2. The **client id** is extracted as the first Common Name from the leaf subject (missing CN
   is `MissingIdentity`).
3. CRL check.
4. Returns the client id, which the handshake records as the session `peer_id`.

The leaf certificate is sent **inline** in the handshake (DER, no intermediate chain); the CA
is the single trust anchor. Possession of the leaf's private key is proven separately by the
handshake signature over the transcript (see `protocol.md`).

Errors surface as `PkiError`: `CertParse`, `EmptyChain`, `TrustAnchor`, `Verification`,
`NameMismatch`, `MissingIdentity`, `Revoked`.

---

## Revocation (CRL)

Aura v1 revocation is deliberately minimal (`crates/aura-pki/src/store.rs`). `CrlStore` is a
**set of revoked identifier strings**, where an identifier is either:

- a certificate **serial number** (lowercase hex, no separators), or
- a **client id / Common Name**.

During verification, if the CRL is non-empty the leaf is rejected (`Revoked`) when **either**
its serial **or** its Common Name is present in the set. An empty CRL skips the check
entirely.

The on-disk format is one identifier per line; blank lines and `#` comments are ignored on
load. `aura pki revoke` / `aura pki list` manage this file.

> v1 limitation: this is a flat allow/deny set, not a signed X.509 CRL. There is no CRL
> signature, no `nextUpdate`, and no automatic distribution — the file must be provisioned to
> the verifying side out of band. The verifier passes `None` for webpki's own revocation
> hooks and relies solely on this set.

---

## Security notes

- **Protect the private keys.** `ca.key` is the root of all trust; anyone with it can mint
  valid server/client certs. `server.key` / `client.key` must stay on their respective hosts.
  The CLI writes them with default file permissions — restrict them at the OS level.
- **The CA is self-signed and unconstrained** (`BasicConstraints: CA` unconstrained). It is
  the sole trust anchor; there is no intermediate CA tier in v1.
- **Server identity is name-bound.** The client only accepts a server leaf whose DNS SAN
  matches the expected name, so a different valid leaf from the same CA will not be accepted
  for the wrong host.
- **Revocation is best-effort** (see above): plan to distribute the CRL file and keep it in
  sync on every server that verifies clients.
- **Leaf lifetime is 365 days**; plan re-issuance. There is no automated rotation in v1.