re-teamspeak/docs/SRS.md

Software Requirements Specification (SRS)

ReTeamSpeak - Cross-Platform TeamSpeak Client

Version: 1.0.0
Date: 2026-05-12
Status: Based on actual implementation

---

1. Introduction

1.1 Purpose

ReTeamSpeak is a cross-platform TeamSpeak 3 voice communication client supporting Windows, macOS, Linux, iOS, and Android. This document specifies the software requirements based on the implemented system.

1.2 Scope

The system implements:

• TeamSpeak 3 protocol (UDP-based, encrypted voice/text communication)
• Cross-platform UI via Tauri v2 + React
• Audio engine with Opus codec
• Local data storage (SQLite)
• Identity and bookmark management

1.3 Definitions

Term	Definition
TS3	TeamSpeak 3 protocol
EAX	AES-128-CTR with OMAC encryption mode
ECDH	Elliptic Curve Diffie-Hellman key exchange
Opus	Audio codec used for voice transmission
VAD	Voice Activity Detection
PTT	Push-To-Talk

---

2. System Requirements

2.1 Functional Requirements

FR-01: Connection Management

• FR-01.1: Connect to TS3 servers via UDP
• FR-01.2: Support RSA puzzle handshake (DoS protection)
• FR-01.3: Support ECDH key exchange (P-256 and Curve25519)
• FR-01.4: Support AES-128-EAX encrypted communication
• FR-01.5: Support QuickLZ packet compression
• FR-01.6: Support packet fragmentation (max 500 bytes)
• FR-01.7: Support selective repeat reliable delivery
• FR-01.8: Support connection state machine (Disconnected → Connecting → Connected → ChannelListFinished)

FR-02: Authentication

• FR-02.1: ECC P-256 identity key generation
• FR-02.2: Hash Cash level computation (anti-spam)
• FR-02.3: Server password authentication (base64(sha1(password)))
• FR-02.4: Channel password authentication
• FR-02.5: Permission token support
• FR-02.6: UID computation (base64(sha1(publicKey)))

FR-03: Voice Communication

• FR-03.1: Opus codec encoding/decoding (48kHz)
• FR-03.2: Voice Activity Detection (VAD)
• FR-03.3: Push-To-Talk (PTT) mode
• FR-03.4: Per-client volume control
• FR-03.5: Whisper support (direct and group)
• FR-03.6: Codec types: Speex NB/WB/UWB, CELT, Opus Voice/Music

FR-04: Text Messaging

• FR-04.1: Server messages
• FR-04.2: Channel messages
• FR-04.3: Private messages
• FR-04.4: BBCode formatting support
• FR-04.5: Message history (SQLite storage)

FR-05: Channel Management

• FR-05.1: Channel tree display
• FR-05.2: Channel join/leave
• FR-05.3: Channel creation/editing (with permissions)
• FR-05.4: Channel subscription

FR-06: Client Management

• FR-06.1: Online client list
• FR-06.2: Client info display
• FR-06.3: Server group management
• FR-06.4: Channel group management
• FR-06.5: Client kick/ban (with permissions)

FR-07: Data Storage

• FR-07.1: Identity storage (encrypted private keys)
• FR-07.2: Server bookmarks
• FR-07.3: Chat message history
• FR-07.4: Application settings

FR-08: File Transfer

• FR-08.1: File upload to channels
• FR-08.2: File download from channels
• FR-08.3: File browsing
• FR-08.4: Transfer progress tracking

2.2 Non-Functional Requirements

NFR-01: Performance

• NFR-01.1: Connection establishment < 3 seconds
• NFR-01.2: Voice latency < 200ms
• NFR-01.3: Message delivery < 100ms
• NFR-01.4: Support 1000+ client servers

NFR-02: Security

• NFR-02.1: AES-128-EAX encryption for all commands
• NFR-02.2: ECDH key exchange (forward secrecy)
• NFR-02.3: RSA puzzle DoS protection
• NFR-02.4: ChaCha20-Poly1305 identity storage encryption

NFR-03: Compatibility

• NFR-03.1: Windows 10/11
• NFR-03.2: macOS 11+
• NFR-03.3: Linux (Ubuntu 20.04+, Debian 11+)
• NFR-03.4: iOS 15+
• NFR-03.5: Android 10+
• NFR-03.6: TS3 server versions 3.0.x and 3.1.x

NFR-04: Reliability

• NFR-04.1: Automatic reconnection on temporary disconnect
• NFR-04.2: Packet retransmission with exponential backoff
• NFR-04.3: Connection timeout detection (30 seconds)
• NFR-04.4: Graceful degradation on packet loss

---

3. System Architecture

3.1 Module Structure

src/
├── shared/          # Shared types (Client, Channel, Server, Events)
├── tscore/          # Protocol core (packets, crypto, connection)
├── tsaudio/         # Audio engine (capture, playback, codec)
├── tsdb/            # Database (SQLite via rusqlite)
└── tauri-app/       # Application shell
    ├── src-tauri/   # Rust backend (Tauri commands)
    └── frontend/    # React frontend (TypeScript)

3.2 Technology Stack

Layer	Technology
Language	Rust 1.70+, TypeScript 5.x
Desktop Framework	Tauri v2
Frontend	React 18, Vite 5
Async Runtime	Tokio
Actor Framework	Actix
Database	SQLite (rusqlite)
Audio	Opus, cpal
Crypto	AES-EAX, P-256, Curve25519, SHA-256/512

---

4. Protocol Specification

4.1 Packet Format

C2S: [MAC:8][PId:2][CId:2][PT:1][Data:≤487]
S2C: [MAC:8][PId:2][PT:1][Data:≤489]

4.2 Packet Types

Type	Value	Encrypted	Reliable	Fragmentable
Voice	0x00	Optional	No	No
VoiceWhisper	0x01	Optional	No	No
Command	0x02	Yes	Yes	Yes
CommandLow	0x03	Yes	Yes	Yes
Ping	0x04	No	No	No
Pong	0x05	No	No	No
Ack	0x06	Yes	Yes	No
AckLow	0x07	Yes	Yes	No
Init	0x08	No	Yes	No

4.3 Handshake Sequence

Client → Server: Init0 (version, timestamp, random0)
Server → Client: Init1 (random1, random0_r)
Client → Server: Init2 (version, random1, random0_r)
Server → Client: Init3 (x, n, level, random2)  [RSA puzzle]
Client → Server: Init4 (x, n, level, random2, y, clientinitiv)
Server → Client: initivexpand2 (beta, omega, proof, license)
Client → Server: clientek (ek, proof)
Server → Client: initserver
Server → Client: channellist...channellistfinished
Server → Client: notifycliententerview...

4.4 Encryption

• Algorithm: AES-128-EAX (AES-128-CTR + OMAC)
• Key derivation: SHA-256(direction | type | generation_id | shared_iv)
• Shared IV: SHA-512(ECDH shared secret) XOR alpha/beta
• MAC: 8 bytes (EAX tag)

---

5. Data Structures

5.1 Core Types (from shared/src/types.rs)

ClientId(u16)        // Client identifier
ChannelId(u64)       // Channel identifier  
ServerGroupId(u64)   // Server group identifier
ClientDbId(u64)      // Client database identifier
Uid(String)          // Unique identifier (base64)
PermissionId(u32)    // Permission identifier

5.2 Database Schema (from tsdb/src/lib.rs)

CREATE TABLE identities (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    private_key TEXT NOT NULL,
    counter INTEGER DEFAULT 0,
    max_counter INTEGER DEFAULT 0,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE TABLE bookmarks (
    id TEXT PRIMARY KEY,
    name TEXT NOT NULL,
    address TEXT NOT NULL,
    port INTEGER DEFAULT 9987,
    nickname TEXT,
    server_password TEXT,
    channel TEXT,
    channel_password TEXT,
    auto_connect INTEGER DEFAULT 0,
    last_connected TEXT,
    created_at TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

CREATE TABLE messages (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    server_address TEXT NOT NULL,
    invoker_id INTEGER NOT NULL,
    invoker_name TEXT NOT NULL,
    invoker_uid TEXT NOT NULL,
    target_type TEXT NOT NULL,
    target_id INTEGER,
    message TEXT NOT NULL,
    is_read INTEGER DEFAULT 0,
    timestamp TEXT NOT NULL
);

CREATE TABLE settings (
    key TEXT PRIMARY KEY,
    value TEXT NOT NULL,
    updated_at TEXT NOT NULL
);

---

6. Test Results

6.1 Unit Tests (32 tests passing)

tscore::protocol::tests - 14 tests
  ✓ test_packet_type_conversion
  ✓ test_flags
  ✓ test_header_c2s
  ✓ test_header_s2c
  ✓ test_in_packet_parse
  ✓ test_out_packet
  ✓ test_command_parse
  ✓ test_command_serialize
  ✓ test_command_builder
  ✓ test_escape_sequences
  ✓ test_init_packet_parse
  ✓ test_init_packet_serialize
  ✓ test_ack_packet
  ✓ test_packet_type_properties

tscore::crypto::tests - 12 tests
  ✓ test_sha1, test_sha256, test_sha512
  ✓ test_hash_password
  ✓ test_create_key_nonce
  ✓ test_create_encryption_key
  ✓ test_shared_secret_old, test_shared_secret_new
  ✓ test_key_cache
  ✓ test_eax_encrypt_decrypt
  ✓ test_fake_encrypt_decrypt
  ✓ test_hash_cash_level
  ✓ test_compute_uid

tscore::connection::tests - 6 tests
  ✓ test_encode_version
  ✓ test_rsa_puzzle
  ✓ test_resend_manager
  ✓ test_rtt_estimator
  ✓ test_sent_packet_retry

---

7. Constraints

7.1 Technical Constraints

• Rust edition 2021
• Tauri v2 for desktop/mobile
• Must maintain TS3 protocol compatibility
• UDP transport only (no TCP fallback)

7.2 Legal Constraints

• TeamSpeak is a trademark of TeamSpeak Systems GmbH
• Implementation is for educational/research purposes
• No server-side code (client-only)

---

8. References

1. TS3 Protocol Paper (refercence/tsdeclarations/ts3protocol.md)
2. Packet Definitions (refercence/tsdeclarations/Packets.txt)
3. Message Definitions (refercence/tsdeclarations/Messages.toml)
4. tsclientlib implementation (refercence/tsclientlib/)
5. Qint implementation (refercence/Qint/)