77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# Connection Key Compression (rtun2) — Design
|
|
|
|
## Goal
|
|
|
|
Shrink the copy-paste connection key string so it is easy to copy and paste, without
|
|
changing any user-facing workflow. A current `rtun1.` key is roughly 4 KB as a single
|
|
unwieldy line; the goal is roughly half that.
|
|
|
|
## Approach
|
|
|
|
Compress the existing JSON payload with pure-Rust DEFLATE (`miniz_oxide`) before
|
|
base64url-encoding. This is a clean break on the wire format:
|
|
|
|
- New keys: `rtun2.` + `base64url(deflate(json))`
|
|
- `decode` accepts only `rtun2.` keys; legacy `rtun1.` keys are dropped (per user decision)
|
|
- `ConnectionKey` struct, CLI, and `listen`/`connect` integration are unchanged
|
|
|
|
## Format
|
|
|
|
```
|
|
rtun2.<base64url-no-padding-of-deflate-of-json>
|
|
```
|
|
|
|
The JSON payload keeps the same shape, with `version` bumped to `2`:
|
|
|
|
```json
|
|
{
|
|
"version": 2,
|
|
"target": "127.0.0.1:4180",
|
|
"ca_cert_pem": "...",
|
|
"server_cert_pem": "...",
|
|
"server_key_pem": "...",
|
|
"client_cert_pem": "...",
|
|
"client_key_pem": "...",
|
|
"auth_token": "..."
|
|
}
|
|
```
|
|
|
|
## Components
|
|
|
|
| File | Change |
|
|
| ---- | ------ |
|
|
| `Cargo.toml` | Add `miniz_oxide` dependency |
|
|
| `src/connkey.rs` | Prefix `rtun2.`, compress on `encode`, decompress on `decode`, version `2` |
|
|
| `src/redact.rs` | `is_connection_key` detects `rtun2.` prefix |
|
|
| Wiki (`droid-wiki/**`) | Document the `rtun2.` format and compression |
|
|
|
|
## Validation
|
|
|
|
`decode` validates, in order:
|
|
|
|
- String starts with `rtun2.`
|
|
- Base64url decode succeeds
|
|
- DEFLATE decompression succeeds
|
|
- JSON deserialization succeeds
|
|
- `version == 2`
|
|
- All string fields non-empty after trim
|
|
|
|
## Testing
|
|
|
|
- Round-trip test: encode → decode returns identical material; assert prefix `rtun2.`
|
|
- Size assertion test: encoded key must be materially smaller than the raw JSON
|
|
(`base64url(json)` without compression), with a generous threshold so the build
|
|
stays robust across certificate size variation
|
|
- Update redaction prefix tests
|
|
|
|
## Docs
|
|
|
|
Update wiki pages that document the key format: `features/connection-keys.md`,
|
|
`reference/data-models.md`, `overview/glossary.md`, `applications/rustunnel-cli.md`,
|
|
`security.md`, and `how-to-contribute/patterns-and-conventions.md`.
|
|
|
|
## Out of scope
|
|
|
|
- QR codes, binary container formats, zstd/brotli, key registry/rotation
|
|
- `generate` command and file-based credential output
|