Files
ts3java/ts3-client/docs/myteamspeak/PROTOCOL.md
T
erikbrockoandClaude Opus 5.5 756e3850a3 myTeamSpeak: two-way sync of bookmarks and identities
MyTeamSpeakSync compares each item against what the last run left: a
change on one side goes to the other, deletions too, and an item changed
on both sides is a conflict for the user. The first run pairs items up by
identity key or bookmark name and address. Edits are written over the
item's Item_Data field by field, so what we do not model survives.

The protocol was probed live and checked against the official client:
the server stores whatever revisions it is sent and never reports a
collision, so the client re-reads the cursors before writing. Edits carry
last_known_version like the official client's, which applies them within
its one-minute poll. All requests now share one session; signing in for
each got the account's logins throttled.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-15 12:37:50 +00:00

89 lines
5.4 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.
### TeamSpeak 6 item classes
The TS6 binary's `Sync_Serializing.proto` is newer than the TS3 one in `myteamspeak.recovered.proto`:
`Item_Class` 7 is `GROUP_CHATS` (TS3: `ROOM_CATEGORY`) and **8 is `CONTACTS`**; `Item_Data` gains oneof
`group_chats(24)` and `contact(25)`. `Contact{chat_room_id(1), custom_name(2), custom_category(3),
notification_preference(4), is_favourite(5), is_direct_chat(6), mytsid(7), chat_member_id(8)}`.
TS6 writes one per chat once a custom name, category or notification setting is set — it is room
settings, not the contact list (that is the Matrix rooms) — and never fills `mytsid`; a direct chat's
`chat_member_id` is the partner's Matrix ID `@<base32 myTS ID bytes>:<homeserver>`. The same bytes as
standard base64 are the `client_myteamspeak_id` servers report (33 bytes, leading `0x01`), which is how
TS6 ties a server client to a chat contact.
## 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
The synchronisation protocol is settled by live probing and capture; see IMPLEMENTATION.md "How the
service and the official client behave". Recovery-key import is not recovered.