# Connection keys

A connection key bundles all credential material and the target address into a single copy-pasteable string.

## Purpose

Simplify distribution of tunnel credentials between machines. Instead of transferring eight separate files, a user can generate one key and paste it into the `listen` and `connect` commands.

## Format

Connection keys start with the prefix `rtun1.` followed by base64url-encoded (no padding) JSON:

```json
{
  "version": 1,
  "target": "198.51.100.10:4180",
  "ca_cert_pem": "-----BEGIN CERTIFICATE-----...",
  "server_cert_pem": "-----BEGIN CERTIFICATE-----...",
  "server_key_pem": "-----BEGIN PRIVATE KEY-----...",
  "client_cert_pem": "-----BEGIN CERTIFICATE-----...",
  "client_key_pem": "-----BEGIN PRIVATE KEY-----...",
  "auth_token": "a1b2c3..."
}
```

## Key abstractions

| Type | File | Description |
| ---- | ---- | ----------- |
| `ConnectionKey` | `src/connkey.rs` | Struct with all fields, version check, validation |
| `ConnectionKey::encode` | `src/connkey.rs` | Serialize to JSON, base64url-encode, prepend prefix |
| `ConnectionKey::decode` | `src/connkey.rs` | Strip prefix, base64url-decode, deserialize, validate |
| `looks_like_connection_key` | `src/connkey.rs` | Quick check if a string starts with `rtun1.` |

## Validation

`decode` validates:

- Prefix must be `rtun1.`
- Base64 decoding must succeed
- JSON deserialization must succeed
- Version must be exactly `1`
- All string fields must be non-empty after trimming

## Integration

`src/main.rs` uses `ConnectionKey::decode` when the `--connection-key` flag or positional argument is provided. The decoded material is passed to `ServerTlsMaterial::Pem` or `ClientTlsMaterial::Pem` variants, which bypass file loading and use the embedded PEM strings directly.

## Entry points for modification

- To change the key format or add versioning: modify `src/connkey.rs`.
- To add compression or encryption: consider extending the encode/decode pipeline in `ConnectionKey`.

## Key source files

| File | Purpose |
| ---- | ------- |
| `src/connkey.rs` | Connection key struct, encoding, decoding, validation |