76 lines
2.5 KiB
Markdown
76 lines
2.5 KiB
Markdown
# TURN REST Credentials (Ephemeral) – Nutzung & Betrieb
|
||
|
||
Dieses Dokument erklärt die **TURN REST Credential** Strategie für `niom-turn` (MVP → production-fähiger Pfad).
|
||
|
||
## Warum TURN REST?
|
||
|
||
- Du willst für WebRTC *kurzlebige* TURN-Logins ausstellen (z.B. 5–10 Minuten).
|
||
- Dein TURN-Server speichert keine User-Passwörter pro Nutzer.
|
||
- Dein Backend (später) kann Tokens ausstellen; bis dahin kannst du lokal/ops-seitig Tokens generieren.
|
||
|
||
## Verfahren (kompatibel zu gängigen WebRTC-Stacks)
|
||
|
||
**Username**: `<expiry_unix_seconds>` oder `<expiry_unix_seconds>:<opaque_user_id>`
|
||
|
||
- Beispiel: `1735412345:alice`
|
||
- `expiry_unix_seconds` ist ein Unix-Timestamp in Sekunden.
|
||
|
||
**Credential (Password)**:
|
||
|
||
$$\n\text{credential} = \text{base64}(\text{HMAC-SHA1}(\text{secret}, \text{username}))\n$$
|
||
|
||
Dieses `credential` wird dann ganz normal als TURN-Passwort im ICE-Server-Config verwendet.
|
||
|
||
## Server-Seite (`niom-turn`)
|
||
|
||
Konfiguration in [appsettings.example.json](../appsettings.example.json):
|
||
|
||
- `auth.rest_secret`: Shared Secret (muss geheim bleiben)
|
||
- `auth.rest_max_ttl_seconds`: Maximal akzeptiertes Zeitfenster in die Zukunft. Wenn ein Token zu weit in der Zukunft liegt, wird es abgewiesen (Sicherheitsmaßnahme).
|
||
|
||
Wichtig:
|
||
- Der Server akzeptiert TURN REST Credentials als Fallback **nur wenn** der Username nicht im CredentialStore gefunden wird.
|
||
- Ablauf/TTL:
|
||
- `expiry` muss >= `now` sein
|
||
- und `expiry - now <= rest_max_ttl_seconds`
|
||
|
||
## Lokal Tokens generieren (ohne Backend)
|
||
|
||
Das Repo enthält ein kleines CLI:
|
||
|
||
- Binary: [src/bin/turn_rest_cred.rs](../src/bin/turn_rest_cred.rs)
|
||
|
||
Beispiele:
|
||
|
||
1) Einfach (stdout als ENV-Zeilen)
|
||
|
||
`cargo run --bin turn_rest_cred -- --secret "SUPER_SECRET" --user alice --ttl 600`
|
||
|
||
2) JSON Ausgabe
|
||
|
||
`cargo run --bin turn_rest_cred -- --secret "SUPER_SECRET" --user alice --ttl 600 --json`
|
||
|
||
Du erhältst:
|
||
- `username` → in WebRTC als `iceServers[].username`
|
||
- `credential` → in WebRTC als `iceServers[].credential`
|
||
|
||
## WebRTC Beispiel (Frontend)
|
||
|
||
Du setzt in deiner App typischerweise:
|
||
|
||
- URLs (mindestens UDP + TLS):
|
||
- `turn:your-domain:3478?transport=udp`
|
||
- `turn:your-domain:3478?transport=tcp`
|
||
- `turns:your-domain:5349?transport=tcp`
|
||
|
||
und dann:
|
||
- `username`: vom Generator/Backend
|
||
- `credential`: vom Generator/Backend
|
||
|
||
## Betriebshinweise
|
||
|
||
- **Secret Rotation**: Plane Rotation (z.B. zwei Secrets parallel) – sonst brechen Tokens im Umlauf.
|
||
- **TTL klein halten**: 5–10 Minuten ist typisch.
|
||
- **Logs**: Niemals `secret` oder vollständige Credentials loggen.
|
||
- **Rate Limits/Quotas**: Unbedingt ergänzen (Open-Relay/Abuse vermeiden).
|