# Connection keys

A connection key is a short random **seed** from which both endpoints derive
identical TLS material on the spot. It is the only value a user must copy/paste
to stand up a tunnel.

## Format

Connection keys are ~49 characters: the prefix `rtun3.` followed by a
base64url-encoded 32-byte seed:

```
rtun3.OH2TI3p1bM2dYjBcHxnLmZT9qKjW8tVvXQ0N7y4E3wA
```

The key ships **no certificates**. Instead, both endpoints derive an identical CA
from the seed and mint ephemeral leaf certificates locally (`src/keyderive.rs`):

- **CA** — Ed25519 keypair from the seed, self-signed and deterministic, so any two
  endpoints that share the seed produce the same CA.
- **Server leaf** — generated at `listen` startup, signed by the derived CA, with
  SANs for the bind address (and optional `--advertise` host).
- **Client leaf** — generated at `connect` startup, signed by the derived CA.
- **Auth token** — derived as `sha256(seed || "rustunnel-auth-token")` (first 16
  bytes hex) and checked in the existing app-layer handshake.

Because the CA is derived from the seed, a connector holding a different seed cannot
authenticate to a listener — possession of the key is what grants access.

## Key abstractions

| Type/Function | File | Description |
| ------------- | ---- | ----------- |
| `ConnectionKey` | `src/connkey.rs` | Seed value, `new`/`encode`/`decode` (rtun3) |
| `derive_server_material` | `src/keyderive.rs` | CA + server leaf PEM for `listen` |
| `derive_client_material` | `src/keyderive.rs` | CA + client leaf PEM for `connect` |
| `derive_auth_token` | `src/keyderive.rs` | App-layer token derived from the seed |
| `looks_like_connection_key` | `src/connkey.rs` | Quick check if a string starts with `rtun3.` |

## Validation

`ConnectionKey::decode` validates:

- Prefix must be `rtun3.` (legacy `rtun1.`/`rtun2.` are rejected)
- Base64url decode succeeds and yields exactly 32 bytes
- The seed is not all zeros

## Integration

`src/main.rs` decodes a seed key (positional arg, `--connection-key`, or
`RUSTUNNEL_KEY`), derives the appropriate material at startup, and feeds the PEMs
into `ServerTlsMaterial::Pem` / `ClientTlsMaterial::Pem`. The TLS layer
(`src/tls.rs`) is unchanged. `connect` requires an explicit `--target`.

## Entry points for modification

- To change derivation or signing parameters: modify `src/keyderive.rs`.
- To change the seed format or versioning: modify `src/connkey.rs`.

## Key source files

| File | Purpose |
| ---- | ------- |
| `src/connkey.rs` | Seed key struct, encoding, decoding |
| `src/keyderive.rs` | CA + leaf + token derivation from the seed |