Sign in to myTeamSpeak and import what the account synchronises

The myTeamSpeak client protocol and its end-to-end encryption are
reverse-engineered (docs/myteamspeak): an HTTP POST of a framed protobuf,
a PBKDF2-HMAC-SHA512 login token and account key, an AES-GCM wrapped
item key and AES-CTR items with a SHA-512 trailer.

Options on desktop and Settings on Android gain a myTeamSpeak page: sign
in and out, and the account's bookmarks and identities, each picked for
import and marked when already here. The client stays signed in the way
the official one does, keeping the derived token and key rather than the
password; each read signs in afresh, and a sign-in the server no longer
takes signs out. Nothing is written to the account.

Items are the same Item_Data as the local TeamSpeak store, so they go
through the existing decoder and importer; a bookmark chosen alone brings
the identity it connects with, found by UUID or, as some name it, by
the identity's name.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-09-26 01:07:17 +00:00
co-authored by Claude Opus 5.5
parent 73a15a8cfc
commit a7aa122728
25 changed files with 3425 additions and 32 deletions
@@ -0,0 +1,65 @@
package com.ts3client.myts;
import org.junit.jupiter.api.Test;
import org.junit.jupiter.api.io.TempDir;
import java.io.File;
import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertThrows;
import static org.junit.jupiter.api.Assertions.assertTrue;
class MyTeamSpeakLoginTest {
@Test
void staysSignedInWithoutKeepingThePassword(@TempDir File dir) throws Exception {
File file = new File(dir, "myteamspeak.properties");
MyTeamSpeakTest.ReplayServer server = new MyTeamSpeakTest.ReplayServer();
MyTeamSpeakLogin login = new MyTeamSpeakLogin(file, new MyTeamSpeak(server));
assertFalse(login.isSignedIn());
login.signIn(MyTsCryptoTest.EMAIL, MyTsCryptoTest.PASSWORD);
assertTrue(login.isSignedIn());
assertEquals("tester", login.username());
assertFalse(Files.readString(file.toPath(), StandardCharsets.ISO_8859_1).contains(MyTsCryptoTest.PASSWORD));
MyTeamSpeakLogin restarted = new MyTeamSpeakLogin(file, new MyTeamSpeak(server));
assertTrue(restarted.isSignedIn());
assertEquals(MyTsCryptoTest.EMAIL, restarted.email());
assertEquals("tester", restarted.username());
assertEquals(1, restarted.fetch().bookmarks());
restarted.signOut();
assertFalse(file.exists());
assertFalse(restarted.isSignedIn());
}
@Test
void aFailedSignInKeepsNothing(@TempDir File dir) {
File file = new File(dir, "myteamspeak.properties");
MyTeamSpeakTest.ReplayServer server = new MyTeamSpeakTest.ReplayServer();
server.loginError = MyTsException.LOGIN_FAILED;
MyTeamSpeakLogin login = new MyTeamSpeakLogin(file, new MyTeamSpeak(server));
assertThrows(MyTsException.class, () -> login.signIn(MyTsCryptoTest.EMAIL, "wrong"));
assertFalse(login.isSignedIn());
assertFalse(file.exists());
}
@Test
void signsOutWhenThePasswordChangedElsewhere(@TempDir File dir) throws Exception {
File file = new File(dir, "myteamspeak.properties");
MyTeamSpeakTest.ReplayServer server = new MyTeamSpeakTest.ReplayServer();
MyTeamSpeakLogin login = new MyTeamSpeakLogin(file, new MyTeamSpeak(server));
login.signIn(MyTsCryptoTest.EMAIL, MyTsCryptoTest.PASSWORD);
server.loginError = MyTsException.LOGIN_FAILED;
MyTsException e = assertThrows(MyTsException.class, login::fetch);
assertTrue(e.credentialsRejected());
assertFalse(login.isSignedIn());
assertFalse(file.exists());
}
}
@@ -0,0 +1,112 @@
package com.ts3client.myts;
import com.ts3client.proto.ProtobufReader;
import com.ts3client.proto.ProtobufWriter;
import com.ts3client.teamspeak.SyncItem;
import org.junit.jupiter.api.Test;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertInstanceOf;
import static org.junit.jupiter.api.Assertions.assertThrows;
class MyTeamSpeakTest {
private static final String SESSION = "00000000-1111-2222-3333-444444444444";
static MyTeamSpeak.Credentials credentials(String password) throws MyTsException {
return MyTeamSpeak.Credentials.derive(MyTsCryptoTest.EMAIL, password);
}
/** Replays the captured account: answers each call and records it. */
static final class ReplayServer implements MyTsTransport {
final List<String> calls = new ArrayList<>();
int loginError = 200;
String loginToken;
@Override
public byte[] call(String endpoint, String method, byte[] request) throws IOException {
calls.add(endpoint + "/" + method);
return switch (method) {
case "login" -> login(request);
case "requestServerItems" -> items(request);
default -> new byte[0];
};
}
private byte[] login(byte[] request) throws IOException {
ProtobufReader r = new ProtobufReader(request);
while (r.next()) {
if (r.fieldNumber() == 2) loginToken = r.readString();
else r.skip();
}
if (loginError != 200) return new ProtobufWriter().varint(5, loginError).toByteArray();
return new ProtobufWriter()
.bytes(1, MyTsCryptoTest.KEY_PACKAGE)
.string(2, SESSION)
.varint(5, 200)
.string(8, "tester")
.toByteArray();
}
private byte[] items(byte[] request) throws IOException {
ProtobufReader r = new ProtobufReader(request);
while (r.next()) {
if (r.fieldNumber() == 1) assertEquals(SESSION, r.readString());
else r.skip();
}
try {
ProtobufWriter bookmark = new ProtobufWriter()
.string(1, "43c5d058-4803-3cd8-b844-15fdcc92e730")
.string(2, "5d831e3c-d5aa-0e66-7af2-a0feb13af048")
.bytes(3, MyTsCryptoTest.itemFrame());
ProtobufWriter tombstone = new ProtobufWriter().string(1, "gone").varint(4, 1);
return new ProtobufWriter()
.varint(1, 301)
.message(2, new ProtobufWriter().varint(1, 0).string(2, "v").message(3, bookmark).message(3, tombstone))
.message(2, new ProtobufWriter().varint(1, 1).varint(4, 1))
.string(3, "g")
.toByteArray();
} catch (java.security.GeneralSecurityException e) {
throw new AssertionError(e);
}
}
}
@Test
void downloadsAndDecryptsTheAccount() throws Exception {
ReplayServer server = new ReplayServer();
MyTeamSpeak.Account account = new MyTeamSpeak(server).download(credentials(MyTsCryptoTest.PASSWORD));
assertEquals("tester", account.username());
assertEquals(1, account.items().size());
SyncItem.Bookmark bookmark = assertInstanceOf(SyncItem.Bookmark.class, account.items().get(0));
assertEquals("server.lixko.eu", bookmark.address());
assertEquals(9987, bookmark.port());
assertEquals("niger", bookmark.nickname());
assertEquals(MyTsCryptoTest.LOGIN_TOKEN, server.loginToken);
assertEquals(List.of("authentication/login", "synchronization/requestServerItems",
"authentication/deleteSession"), server.calls);
}
@Test
void reportsAWrongPassword() {
ReplayServer server = new ReplayServer();
server.loginError = 202;
MyTsException e = assertThrows(MyTsException.class,
() -> new MyTeamSpeak(server).download(credentials("wrong")));
assertEquals(202, e.code());
assertEquals(List.of("authentication/login"), server.calls);
}
@Test
void signsOutWhenTheKeyDoesNotOpen() {
// The server accepted the login token but the key does not open with this password.
ReplayServer server = new ReplayServer();
assertThrows(MyTsException.class, () -> new MyTeamSpeak(server).download(credentials("other")));
assertEquals("authentication/deleteSession", server.calls.get(server.calls.size() - 1));
}
}
@@ -0,0 +1,117 @@
package com.ts3client.myts;
import org.junit.jupiter.api.Test;
import javax.crypto.Cipher;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.GeneralSecurityException;
import java.security.MessageDigest;
import java.util.Arrays;
import java.util.HexFormat;
import static org.junit.jupiter.api.Assertions.assertArrayEquals;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertThrows;
/**
* Vectors from the official client (see CRYPTO_RE_SALT.md). The sign-in sample is a login the client
* computed for an address with no account; the item is a real captured one with its item key.
*/
class MyTsCryptoTest {
static final String EMAIL = "probe.nobody@example.com";
static final String PASSWORD = "wrongpassword1";
static final String LOGIN_TOKEN = "kJLau9cQuYPQi/hi0ey4dPBChwvTMhz2lfAYHWQnNNtaVffCzHHac8mIFVb2FpN4";
static final byte[] ITEM_KEY = hex("22efa5d631ddaa11ec97ccb82846b4d24598a9376319f444b5065cd47b391b2d");
/** {@code LoginSession.key} sealing {@link #ITEM_KEY} for {@link #EMAIL}, laid out as the server sends it. */
static final byte[] KEY_PACKAGE = keyPackage();
/** A bookmark: server.lixko.eu:9987, nickname "niger". */
static final byte[] ITEM_DATA = hex("122434336335643035382d343830332d336364382d623834342d3135666463633932653733301a24"
+ "64373663663736312d316163332d373434662d366234312d36363633386362643165303320003000"
+ "3a00420048f7f5dbd506820189010a19457269c48d516f76205465616d537065616b207365727665"
+ "72120f7365727665722e6c69786b6f2e657518834e22056e696765722a00320744656661756c743a"
+ "0042004a0050005a0744656661756c74620744656661756c746a0070007a1c2b547967324a747845"
+ "3876524e5a702b4a6955426e6d4268304d593d8a0100900100980100b00101");
/** The capture cut the frame 37 bytes into its SHA-512 trailer, so the test completes it. */
static byte[] itemFrame() throws GeneralSecurityException {
byte[] captured = hex("1114428e2059c038f339b1c1a6bc4eb0eac1f4479ec2764ea53c0b4dd0fc4626"
+ "4642cab8908d295933fac43152154f58990909e933d899b86d4776ae8c52f61575b33932d4667fc3f"
+ "b50e78a2a056dc6c8cd74e3e2446275e0d351c7139bc686a3555b4dd3dd6fdfae1c7176e84f99b3"
+ "0df52dbe9b95e28d9545e2dd3188fec7e34ac233fb7de6d21db8795a45186ff91a01d23189d072d6"
+ "afb60cad9b1c834e35acf04006daa1d6e439750afaa00a4c63e53f10cf54d2820108c1b859b394d0"
+ "ba7d80b38de402b631da9ba4daedbff4d9de85cdeae7466b516ac5abe9af4d43e9df1c9bf8951d1"
+ "2e9f5c42ce7cf802443d4bc051902164ec510126130dd962e54778518ae0a44947e6dd19975eef8b"
+ "33ce8");
byte[] hash = MessageDigest.getInstance("SHA-512").digest(ITEM_DATA);
byte[] frame = Arrays.copyOf(captured, 16 + ITEM_DATA.length + hash.length);
System.arraycopy(hash, 0, frame, 16 + ITEM_DATA.length, hash.length);
return frame;
}
@Test
void derivesTheOfficialLoginToken() throws GeneralSecurityException {
assertEquals(LOGIN_TOKEN, MyTsCrypto.loginToken(EMAIL, PASSWORD));
}
@Test
void emailCaseDoesNotMatter() throws GeneralSecurityException {
assertEquals(LOGIN_TOKEN, MyTsCrypto.loginToken("Probe.Nobody@EXAMPLE.com", PASSWORD));
}
/** The same construction opened a real account's key; this pins it for the sample address. */
@Test
void derivesTheAccountKey() throws GeneralSecurityException {
assertArrayEquals(hex("f0e2ba6d60d69c8eb6bb9e56f0093490db7379b3f4df5475599ddad2a750d00d"),
MyTsCrypto.accountKey(EMAIL, PASSWORD));
}
@Test
void unwrapsTheItemKey() throws GeneralSecurityException {
assertArrayEquals(ITEM_KEY, MyTsCrypto.unwrapItemKey(MyTsCrypto.accountKey(EMAIL, PASSWORD), KEY_PACKAGE));
}
@Test
void wrongPasswordCannotUnwrap() throws GeneralSecurityException {
byte[] accountKey = MyTsCrypto.accountKey(EMAIL, "not the password");
assertThrows(GeneralSecurityException.class, () -> MyTsCrypto.unwrapItemKey(accountKey, KEY_PACKAGE));
}
@Test
void decryptsAnItem() throws GeneralSecurityException {
assertArrayEquals(ITEM_DATA, MyTsCrypto.decryptItem(itemFrame(), ITEM_KEY));
}
@Test
void rejectsATamperedItem() throws GeneralSecurityException {
byte[] frame = itemFrame();
frame[40] ^= 1;
assertThrows(GeneralSecurityException.class, () -> MyTsCrypto.decryptItem(frame, ITEM_KEY));
}
/** {@code 02 || tag || iv || ciphertext}; JCA puts the tag last, the server first. */
private static byte[] keyPackage() {
try {
byte[] iv = hex("0102030405060708090a0b0c");
Cipher gcm = Cipher.getInstance("AES/GCM/NoPadding");
gcm.init(Cipher.ENCRYPT_MODE, new SecretKeySpec(MyTsCrypto.accountKey(EMAIL, PASSWORD), "AES"),
new GCMParameterSpec(128, iv));
byte[] sealed = gcm.doFinal(ITEM_KEY);
byte[] out = new byte[1 + 16 + 12 + 32];
out[0] = 2;
System.arraycopy(sealed, 32, out, 1, 16);
System.arraycopy(iv, 0, out, 17, 12);
System.arraycopy(sealed, 0, out, 29, 32);
return out;
} catch (GeneralSecurityException e) {
throw new AssertionError(e);
}
}
static byte[] hex(String s) {
return HexFormat.of().parseHex(s);
}
}
@@ -15,6 +15,7 @@ import java.nio.file.Path;
import java.util.List;
import static org.junit.jupiter.api.Assertions.assertEquals;
import static org.junit.jupiter.api.Assertions.assertFalse;
import static org.junit.jupiter.api.Assertions.assertNotNull;
import static org.junit.jupiter.api.Assertions.assertTrue;
@@ -75,6 +76,40 @@ class TeamSpeakImporterTest {
assertEquals(1, identities.all().size());
}
@Test
void resolvesABookmarkNamingItsIdentity() throws Exception {
Settings settings = new Settings();
IdentityStore identities = IdentityStore.load(settings);
Bookmarks bookmarks = new Bookmarks();
SyncItem.Identity identity = TeamSpeakSettingsDb.readSyncItems(SyncItemsTest.fixture()).stream()
.filter(SyncItem.Identity.class::isInstance).map(SyncItem.Identity.class::cast).findFirst().orElseThrow();
SyncItem.Bookmark bookmark = new SyncItem.Bookmark("b", "", "Server", "example.com", 9987, "", "",
identity.name(), "", "", "", 0, false);
new TeamSpeakImporter(identities, bookmarks, settings).importAll(List.of(bookmark, identity));
assertEquals(identities.all().get(0).getId(), bookmarks.all().get(0).identityId);
assertEquals(identity.nickname(), bookmarks.all().get(0).nickname);
}
@Test
void importsTheSelectionWithTheIdentitiesItNeeds() throws Exception {
Settings settings = new Settings();
IdentityStore identities = IdentityStore.load(settings);
Bookmarks bookmarks = new Bookmarks();
TeamSpeakImporter importer = new TeamSpeakImporter(identities, bookmarks, settings);
List<SyncItem> all = TeamSpeakSettingsDb.readSyncItems(SyncItemsTest.fixture());
SyncItem.Bookmark lixko = all.stream().filter(SyncItem.Bookmark.class::isInstance)
.map(SyncItem.Bookmark.class::cast).filter(b -> b.name().equals("Lixko")).findFirst().orElseThrow();
assertFalse(importer.isPresent(lixko));
TeamSpeakImporter.Result result = importer.importSelected(all, List.of(lixko));
assertEquals(1, result.bookmarksAdded());
assertEquals(1, result.identitiesAdded(), "the identity the bookmark connects with");
assertEquals(identities.all().get(0).getId(), bookmarks.all().get(0).identityId);
assertTrue(importer.isPresent(lixko));
assertTrue(all.stream().filter(SyncItem.Identity.class::isInstance).allMatch(importer::isPresent));
}
@Test
void identityImportRecognisesAKnownKey() throws Exception {
Settings settings = new Settings();