rustunnel/droid-wiki/features/connection-keys.md

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:

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