Files
ts3java/ts3-client/docs/myteamspeak/PROTOCOL.md
T
erikbrockoandClaude Opus 5.5 78fc45f9b2 Rename to TeamSpook TS3j, package eu.lixko.ts3j.client
Java/Kotlin sources move from com.ts3client to eu.lixko.ts3j.client, and
the Android application id becomes eu.lixko.ts3j.client. The product name
shows as "TeamSpook TS3j" in window titles, the tray, the launcher entries,
notifications and PipeWire streams.

The desktop profile directory, WM_CLASS and ts3j.* system properties keep
their names so existing settings and launchers carry on working.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 14:43:34 +00:00

82 lines
5.0 KiB
Markdown

# myTeamSpeak client protocol (reverse-engineered)
Recovered from the official TS3 client binaries (`TeamSpeak3-Client-linux_amd64/ts3client_linux_amd64`
and `re-android/.../libteamspeak_client.so`) plus a captured real login/sync session. This documents
what is needed to talk to myTeamSpeak for synchronization of bookmarks/identities/etc.
## Transport
Not gRPC-over-HTTP2 in the usual sense. It is **HTTP/1.1 POST** (cpp-httplib client) to:
https://clientapi.myteamspeak.com/<endpoint>
Endpoints: `authentication`, `session`, `synchronization`, `user`, `integration`, `messenger`, `tschat`, `addon`.
Headers: `Content-Type: application/ts3cloud`, `Accept: */*`, `Connection: close`,
`User-Agent: cpp-httplib/0.11.1`. Cloudflare fronts it and 403s anything that doesn't look right.
Request body framing:
<1 byte: len of method name> <method-name ASCII> <serialized protobuf request>
e.g. `05 "login" <LoginData>`, `12 "requestServerItems" <Sync_Request_ItemClasses>`.
Response body = the serialized protobuf reply (Content-Type comes back `application/json` but the
body is protobuf, not JSON).
## Services / methods (see myteamspeak.recovered.proto for full schemas)
- **LoginService** (`/authentication`): `login(LoginData) -> LoginSession`,
`loginWithAuthToken`, `loginWithRenewalToken`, `session`, `deleteSession`, `requestAuthToken`.
- **SynchronizationService** (`/synchronization`):
`requestServerItems(Sync_Request_ItemClasses) -> Sync_Reply_ItemClasses` (download),
`synchronizeItems(...)` (upload/merge).
### Login flow (observed)
1. POST `/authentication` `login` with `LoginData{email(1), password(2)}`.
`password` is NOT the plaintext — see Crypto below.
2. Reply `LoginSession`: `key(1)`, `session(2)=UUID` (bearer for later calls),
`limits(3)`, `uuid(4)`, `error(5)=200` on success (ErrorCommon.ERROR_LOGIN_OK),
`purge(6)`, `username(8)`, `myts_id_data(9)=MyTeamSpeakIdData`, `mytsid_user_cert(10)`,
`alternative_login_info(16).renewal_token`.
3. POST `/synchronization` `requestServerItems` with `{session(1), classes(2), globalversion(3)}`.
Advertise each local item as `{item_uuid(1), item_version(2)}` where `item_version` is exactly the
local plaintext `Item_Data.sync_version_uuid`; the initial request builder does not attach blobs.
4. Reconcile the server's comparison reply. Decrypt any returned `item_blob`, honor deletion/not-in-db
details, and retain its opaque global and per-class version cursors.
5. If local changes are requested, POST `synchronizeItems` with those reply cursors. Adds/changes carry
the full encrypted `Item_Data` frame; deletions use the detail deletion flag. See
[CRYPTO_RE_SALT.md](CRYPTO_RE_SALT.md#5-synchronization-and-upload-state-machine) for the recovered
state machine and confidence boundaries.
## Crypto status
myTeamSpeak sync is **end-to-end encrypted**, using TeamSpeak's own `teamcrypto` library
(AES-256-GCM + SHA-2 via mbedtls + a CTR-DRBG), statically linked — NOT OpenSSL's KDFs and
NOT libsodium. This is why the sync store on disk is plaintext but the wire blobs are not.
Recovered constructions:
- The login `password` field is base64 of 48 bytes from PBKDF2-HMAC-SHA512 with 10,000 iterations:
password=`password`, salt=`asciiLower(email) + "ts3Login" + password`.
- The account wrapping key is the same KDF with salt purpose `ts3Encryption` and a 32-byte output.
- `LoginSession.key` v2 is `02 || GCM-tag[16] || IV[12] || ciphertext[32]`, AES-256-GCM without AAD.
Its plaintext is the 32-byte item key.
- `MyTeamSpeakIdData`: `user_public_key(1)` = 32 bytes (X25519/Ed25519),
`user_private_key(2).encrypted_user_private_key` = 112 bytes (the account private key, wrapped
by a password-derived key), `account_creation_time(3)`, `my_teamspeak_id(4)` = `01 20 <32 bytes>`,
`public_signature(5)`.
- `Account_Data` / `Auth_Token_Package` show the recovery model:
`encrypted_encryption_password`, `encryption_tag`, `iv` — a random data key wrapped by the
password-derived key, and separately by the **recovery key** (32 bytes, base64), so the recovery
key is the route to decrypt items without the password.
- Item blobs are `IV[16] || AES-256-CTR ciphertext || SHA512(plaintext)`. CTR increments its full
128-bit counter little-endian. The original capture contained the complete ciphertext but only the
first 27 of 64 digest bytes; those bytes exactly match the recovered plaintext hash.
## Remaining reverse-engineering gaps
Password login, key unwrap, item encryption/integrity framing, two-phase comparison, and the local
manipulation flags are recovered. The remaining uncertainties are narrower: where ordinary edits rotate
`sync_version_uuid`, the exact lifecycle of `last_known_version`, the official collision winner/merge
policy, and instruction-level confirmation of the deletion-detail builder. Recovery-key import is also
not yet recovered. The read-only pull is implemented in `eu.lixko.ts3j.client.myts` (see IMPLEMENTATION.md); destructive upload
should remain gated until the deletion mapping has a fixture or controlled integration test.