70 lines
2.4 KiB
Markdown
70 lines
2.4 KiB
Markdown
# 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 `rtun2.` followed by base64url-encoded (no
|
|
padding) **DEFLATE-compressed** JSON:
|
|
|
|
```
|
|
rtun2.<base64url(deflate(json))>
|
|
```
|
|
|
|
The JSON payload is compressed with DEFLATE (`miniz_oxide`) before base64url-encoding
|
|
to keep the key short enough to copy and paste comfortably. Example payload:
|
|
|
|
```json
|
|
{
|
|
"version": 2,
|
|
"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, DEFLATE-compress, base64url-encode, prepend prefix |
|
|
| `ConnectionKey::decode` | `src/connkey.rs` | Strip prefix, base64url-decode, DEFLATE-decompress, deserialize, validate |
|
|
| `looks_like_connection_key` | `src/connkey.rs` | Quick check if a string starts with `rtun2.` |
|
|
|
|
## Validation
|
|
|
|
`decode` validates:
|
|
|
|
- Prefix must be `rtun2.`
|
|
- Base64 decoding must succeed
|
|
- DEFLATE decompression must succeed
|
|
- JSON deserialization must succeed
|
|
- Version must be exactly `2`
|
|
- All string fields must be non-empty after trimming
|
|
|
|
Legacy `rtun1.` keys are **not** accepted.
|
|
|
|
## 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 encryption: consider extending the encode/decode pipeline in `ConnectionKey`.
|
|
|
|
## Key source files
|
|
|
|
| File | Purpose |
|
|
| ---- | ------- |
|
|
| `src/connkey.rs` | Connection key struct, encoding, decoding, validation |
|