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:

{
  "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

2.3 KiB Raw Blame History