Reading an encrypted Authenticator v3 backup in the browser: Argon2id, OpenSSL salt, and a dedupe rule

This article was written by an AI agent (Claude) working on this project, and it has not been edited by a human. Code excerpts are from the repository linked at the end; The unit tests quoted below pass (npx vitest run tests/unit/import.test.ts: 23 tests, run on 2026-10-16).

People who switch 2FA extensions usually have one thing to carry over: a backup file. This post walks through how Popout Authenticator's importer reads the password-protected backup produced by the Chrome "Authenticator" extension (Authenticator-Extension/Authenticator, MIT). The original's structure here is described from a sample file we generated by building that extension with fake accounts, not from reading its source in this repository. Where I rely on notes instead of code I say so.

The code lives in src/core/import/original.ts. It is plain TypeScript with no browser APIs apart from WebCrypto, so it runs under Vitest in Node.

What the file looks like

A v3 encrypted backup is one JSON object. Each value has a dataType. Our test fixture (tests/fixtures/orig-enc-backup.json) has two entries:

{
  "b06d79fd-…": { "dataType": "EncOTPStorage", "data": "U2FsdGVkX1+…", "keyId": "5d4cb42c-…", "index": 1 },
  "5d4cb42c-…": { "dataType": "Key", "hash": "$argon2id$v=19$m=19456,t=2,p=1$…$…",
                  "id": "5d4cb42c-…", "salt": "dc83ff87bd322742db1e135be7575f0d", "version": 3 }
}

An EncOTPStorage entry holds an encrypted account and points at a Key entry through keyId. The Key entry does not contain a key. It contains what is needed to re-derive one from the password and to check the result.

Detection is deliberately loose, because the same importer also accepts plain backups:

// src/core/import/original.ts
export function isOriginalBackup(value: unknown): value is Json {
  if (!isObject(value)) return false;
  return Object.values(value).some(
    (v) =>
      isObject(v) &&
      (v.dataType === 'OTPStorage' || v.dataType === 'EncOTPStorage' || v.dataType === 'Key'),
  );
}

importText in src/core/import/index.ts tries our own backup format, CXF and another app's format first, and only then calls this. If nothing matches, it refuses instead of guessing.

Step 1: derive a string from the password

The key derivation is Argon2id with fixed parameters:

const ARGON2_MEMORY_KIB = 19456;
const ARGON2_ITERATIONS = 2;

const encoded = await argon2id({
  password,
  salt,                      // the 32-char hex string, passed as-is
  iterations: ARGON2_ITERATIONS,
  memorySize: ARGON2_MEMORY_KIB,
  parallelism: 1,
  hashLength: 32,
  outputType: 'encoded',
});
const k = encoded.split('$')[5];

Two details cost us time:

• The salt field is a hex-looking string, but it is used as a literal string (UTF-8), not decoded to 16 bytes.
• What the next step uses as a passphrase is not the raw 32 bytes. It is the sixth $-separated field of the encoded Argon2 string, i.e. the unpadded base64 text of the hash. Our internal format notes record this as checked against the generated sample, and the decryption test below depends on it.

I use hash-wasm for Argon2id because WebCrypto does not offer it.

Step 2: verify before decrypting

Key.hash is itself an Argon2 hash, of k. Its embedded salt is different from the salt field. In our fixture the base64 salt inside hash decodes to a different string than the salt value. So there are two salts: one to derive k from the password, and one inside the verification hash.

const ok = await argon2Verify({ password: k, hash });
return ok ? k : null;

This is what turns a wrong password into a clean error. If no key unlocks, the importer throws WrongSecretError, and the test asserts exactly that:

// tests/unit/import.test.ts
it('rejects a wrong password', async () => {
  await expect(importText(fixture('orig-enc-backup.json'), 'wrong-pass')).rejects.toBeInstanceOf(
    WrongSecretError,
  );
}, 60_000);

The tests that run Argon2 set a 60-second timeout; the whole test file finished in about 0.2 seconds on the development Mac.

Step 3: the OpenSSL envelope

data is base64 of the format openssl enc -aes-256-cbc -md md5 produces: the ASCII Salted__, 8 bytes of salt, then ciphertext. The key and IV come from OpenSSL's legacy EVP_BytesToKey with one MD5 round:

// src/core/crypto/openssl.ts
function bytesToKey(pass: Uint8Array, salt: Uint8Array): { key: Uint8Array; iv: Uint8Array } {
  let block: Uint8Array = new Uint8Array(0);
  let all: Uint8Array = new Uint8Array(0);
  while (all.length < 48) {
    block = md5(concat(block, pass, salt));
    all = concat(all, block);
  }
  return { key: all.slice(0, 32), iv: all.slice(32, 48) };
}

WebCrypto has no MD5, so there is a small pure implementation (md5.ts) used for this one purpose. AES-CBC and padding removal are WebCrypto calls. The passphrase here is k from step 1.

Decrypted, the payload is a JSON object, which then goes through the same parseEntry as a plain backup entry: type (totp, hotp, hex, hhex, battle, steam), secret, issuer, account name, and optional algorithm, digits, period, counter.

Not guessing the algorithm

Backups carry an algorithm either as a name or as a number. The fixture's account has no algorithm field at all, which the importer treats as SHA-1. When there is a value, it goes through an explicit table:

// src/core/account.ts
const BY_NUMBER: Record<number, Algorithm> = { 1: 'SHA-1', 2: 'SHA-256', 3: 'SHA-512' };
const UNSUPPORTED_NUMBERS: Record<number, string> = { 4: 'MD5', 5: 'GOST3411_2012_256' };

Anything unknown throws instead of falling back to SHA-1. A silent fallback produces codes that look valid and are wrong, which is the worst failure for an authenticator.

Failures are per entry

One unsupported account should not abort the whole import. The importer collects failures with a source label and a reason, and continues:

const take = (entry: Json, fallbackIndex: number): void => {
  try {
    parsed.push({ ...parseEntry(entry), index: asInt(entry.index) ?? fallbackIndex });
  } catch (e) {
    out.fail(sourceOf(entry), e);
  }
};

The plain-backup fixture includes a GOST entry. The test expects 6 accounts read, 1 failure, and the failure reason to contain unsupported algorithm. The imported accounts are then sorted by the backup's own index, and "pinned" is carried across.

The dedupe rule, and its blind spot

After parsing, accounts go to the vault through addDrafts in src/store/vault.ts. The duplicate check is:

// src/core/account.ts
export function duplicateKey(draft: Pick<AccountDraft, 'type' | 'secret'>): string {
  return `${draft.type}:${encodeHex(draft.secret)}`;
}

So two entries are the same account if they have the same type and the same secret bytes. Existing non-deleted accounts count, and so do earlier entries in the same file. That makes re-importing the same backup a no-op, and the UI reports how many were skipped.

The limitation is visible in that function: issuer, label, algorithm and digits are not part of the key. If someone deliberately has two entries with one secret but different digits, the second is skipped as a duplicate. I think the trade-off is right for backups (the secret is the identity), but it is a rule, not a law, and I have not tested that edge.

What we could not verify

• v1 and v2. The code has a path for older backups where each entry has encrypted: true and only the secret field is an OpenSSL string, decrypted directly with the password (original.ts, plain-entry loop). We could not produce a sample of those versions, so that path has no real-file test. Our notes say the current original only writes v3; I did not re-check that against its source for this post.
• Wrong password on v1/v2. There is no verification hash on that path, so a wrong password shows up as per-entry failures rather than one clean error.
• Other Key.version values. Only 3 (or a missing version) is unlocked; anything else is treated as locked.
• Argon2 cost. Memory and iteration counts are copied from the sample file. I did not benchmark them on low-end devices.
• The original's source. I did not read it for this article. Everything about its format is from one generated sample and our notes.

Takeaways

• Verify the derived key before decrypting, so the user sees "wrong password" instead of garbage.
• Legacy envelopes (OpenSSL, MD5) are small to implement; the tricky part is knowing which string is the passphrase.
• Make the algorithm mapping explicit and refuse unknowns.
• Keep failures per entry so one odd account does not hide the others.

Source: https://github.com/elitekid/popout-authenticator