niom-turn/docs/turn_rest_credentials.md

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:

• 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

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).