Files
ts3java/ts3-client/docs/myteamspeak/PROTOCOL.md
T
erikbrockoandClaude Opus 5.5 ca86c510b7 myTeamSpeak: import TeamSpeak 6 contacts; bookmark myTeamSpeak switch
TeamSpeak 6 syncs chat contacts as item class 8 (Item_Data field 25). They
are imported as friends keyed by myTeamSpeak ID, taken from the item or from
the partner's chat ID (@<base32 id>:<homeserver>), the same bytes servers
report as base64 client_myteamspeak_id. The contact list matches them to
clients through the ID each client carries.

Bookmarks gain TeamSpeak's "Enable myTeamSpeak features" switch
(send_mytsid_on_server), stored and imported but not yet sent; what is
still missing is noted in docs/myteamspeak/myteamspeak_server_signin.md.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-10 17:56:29 +00:00

5.9 KiB

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

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.