Keys backup tutorial

[pashky]

Hello stranger.

So I'm assuming you lurking here in the same situation as I was - trying to find out a way to backup or port your one time tokens from iOS app.

Thanks to the clues left by @Esgariot in #412 I was able to figure the process out. I'm not going to go into too many details for each step, if something doesn't make sense you'll have to google it.

1. Make an encrypted backup keeping note of the password you set
2. Run go install github.com/dunhamsteve/ios/cmd/irestore@latest. Install golang first if you don't have it.
3. Run irestore it should display a list with your backup like iphone 00000000-0000000000000000
4. Run irestore 00000000-0000000000000000 dumpkeys keys.json entering the password from step1
5. Run this python script. Obviously you'll need python installed.

#!/usr/bin/env python3
import json
from base64 import b64decode, b32encode

with open('keys.json') as file:
    j = json.load(file)
    for c in j['General']:
        if 'svce' in c and c['svce'] == 'me.mattrubin.onetimepassword.token':
            url = b64decode(c['gena']).decode('utf-8')
            secret = b32encode(b64decode(c['v_Data'])).decode('utf-8')
            print("{0}&secret={1}".format(url, secret))

The script will print a bunch of URLs in the form of otpauth://totp/... complete with secrets.

You can now open them in Safari one by one to add to iOS or OSX built-in keychain which now has code generator integrated. Or use just a secret string to import items into your other token app.

[joshperry]

Thanks for figuring this out! I'm moving to android and really didn't want to go through every site to add my new phone. I paired this with qrrs to generate qr codes in my shell and imported them quickly into an app that has an encrypted export feature.

[tkrn]

I just wanted to report this extraction method absolutely worked! Thank you! Also, here your Python script modified to output it into Yubikey (ykman) CLI format.

#!/usr/bin/env python3
import json
from base64 import b64decode, b32encode
from urllib.parse import urlparse, parse_qs

with open('keys.json') as file:
    j = json.load(file)
    for c in j['General']:
        if 'svce' in c and c['svce'] == 'me.mattrubin.onetimepassword.token':
            url = b64decode(c['gena']).decode('utf-8')
            secret = b32encode(b64decode(c['v_Data'])).decode('utf-8')
            fullstring = "{0}&secret={1}".format(url, secret)
            u = urlparse(fullstring)
            params = parse_qs(u.query)
            result = {
                "scheme": u.scheme,
                "type": u.netloc,
                "label": u.path.lstrip("/"),
                "algorithm": params["algorithm"][0],
                "digits": params["digits"][0],
                "issuer": params["issuer"][0],
                "period": params["period"][0],
                "secret": params["secret"][0],
            }
            ykmanstring = "ykman oath accounts add -i '{0}' -a {1} -d {2} -P {3} '{4}' '{5}'".format(result["issuer"],
                result["algorithm"],
                result["digits"],
                result["period"],
                result["label"],
                result["secret"])
            print(ykmanstring)

It'll output like this for you to execute.

ykman oath accounts add -i 'OPNsense' -a SHA1 -d 6 -P 30 'root@firewall' 'WPQFT5ARX6MK0T2VP69U7QQ6P8'
ykman oath accounts add -i 'Credly' -a SHA1 -d 6 -P 30 'credly@company.com' 'X6MYHC82XXM2K0T2VP69U7QQ6P8'
ykman oath accounts add -i 'ExaGrid' -a SHA1 -d 6 -P 30 'admin-lab' 'WPQFT5ARX6MYHC82XXM2K0T2VP69U7QQ6P8'

[linuxus]

Tip

Repo with all scripts ready to clone: https://github.com/linuxus/authenticator-export
The same three files are inlined below for anyone who prefers to read them on this page; both paths work.

Big thanks to @pashky for the original recipe — that exact sequence got me unstuck and I just used it to migrate every TOTP off the iOS app onto a new iPhone running Microsoft Authenticator. Sharing a small wrapper around the same approach because the painful step for me was step 5 (opening every otpauth:// URI in Safari one at a time, then re-keying / re-scanning into the destination app). With 30+ accounts that gets old fast.

The underlying technique is unchanged — irestore + the same parsing logic. The wrapper just bundles it into one shell script and emits a single self-contained HTML page with a scannable QR code per token, so the new phone scans them in directly. Tested on macOS only.

What's different

• One script orchestrates the pipeline (encrypted-backup → keychain dump → URI extraction → QR-code page).
• Output is one HTML file: each token rendered as an inline-SVG QR with its issuer/account label and a "scanned" checkbox so you don't lose your place. On the new phone open any standard authenticator app (Microsoft Authenticator, Ente Auth, 2FAS, Aegis, etc.) → Add account → Other → scan.
• Secrets are kept out of cloud-synced folders. All output lands in ~/authenticator-migration/, not the script's own folder. The script refuses to run if the work directory's path looks cloud-synced (OneDrive, iCloud, Dropbox, Google Drive).
• Malformed/unrelated Keychain entries are skipped with a warning instead of crashing the whole run.

Files

Save these three files into the same folder, chmod +x migrate.sh, then run ./migrate.sh.

extract.py

#!/usr/bin/env python3
"""Parse irestore keychain dump → otpauth:// URIs.

Reads keys.json from `irestore <udid> dumpkeys keys.json`, filters Keychain
entries owned by the mattrubin Authenticator app, reconstructs the full
otpauth URI (URL prefix + base32-encoded secret) for each token, and writes
one URI per line to stdout. Diagnostics go to stderr.
"""
from __future__ import annotations

import json
import sys
from base64 import b32encode, b64decode

SVCE = "me.mattrubin.onetimepassword.token"


def main(path: str) -> int:
    with open(path) as f:
        data = json.load(f)

    entries = data.get("General", [])
    found = 0
    skipped = 0

    for entry in entries:
        if entry.get("svce") != SVCE:
            continue
        try:
            url_prefix = b64decode(entry["gena"]).decode("utf-8")
            secret_b32 = b32encode(b64decode(entry["v_Data"])).decode("utf-8").rstrip("=")
        except (KeyError, ValueError, UnicodeDecodeError) as e:
            print(f"warning: skipping malformed entry ({e})", file=sys.stderr)
            skipped += 1
            continue

        sep = "&" if "?" in url_prefix else "?"
        print(f"{url_prefix}{sep}secret={secret_b32}")
        found += 1

    print(f"extracted {found} token(s); skipped {skipped}", file=sys.stderr)
    return 0 if found > 0 else 1


if __name__ == "__main__":
    if len(sys.argv) != 2:
        print("usage: extract.py <keys.json>", file=sys.stderr)
        sys.exit(2)
    sys.exit(main(sys.argv[1]))

render_qrs.py

#!/usr/bin/env python3
"""Render otpauth:// URIs as a single self-contained HTML page of QR codes.

Reads one URI per line (file arg or stdin), shells out to `qrencode -t SVG`
for each, and emits an HTML page with inline SVG QR codes plus a checkbox
per token so you can track progress while scanning on the new phone.
"""
from __future__ import annotations

import html
import subprocess
import sys
from urllib.parse import parse_qs, unquote, urlparse


def parse_label(uri: str) -> tuple[str, str]:
    """Return (issuer, account) for display purposes."""
    p = urlparse(uri)
    path = unquote(p.path.lstrip("/"))
    qs = parse_qs(p.query)
    issuer_q = qs.get("issuer", [""])[0]

    if ":" in path:
        issuer_l, account = path.split(":", 1)
    else:
        issuer_l, account = "", path
    issuer = issuer_q or issuer_l or "(unknown)"
    return issuer, account or "(no account)"


def qr_svg(uri: str) -> str:
    out = subprocess.run(
        ["qrencode", "-t", "SVG", "-o", "-", "--", uri],
        check=True,
        capture_output=True,
    ).stdout.decode("utf-8")
    if out.startswith("<?xml"):
        out = out.split("?>", 1)[1].lstrip()
    return out


HEAD = """<!doctype html>
<html lang="en"><head><meta charset="utf-8">
<title>TOTP migration</title>
<style>
  body { font-family: -apple-system, system-ui, sans-serif; margin: 2rem; background: #f7f7f8; }
  h1 { margin: 0 0 0.25rem; }
  .hint { color: #555; margin-bottom: 1.5rem; }
  .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); gap: 1rem; }
  .card { background: #fff; border: 1px solid #ddd; border-radius: 12px; padding: 1rem;
          box-shadow: 0 1px 2px rgba(0,0,0,0.04); display: flex; flex-direction: column; }
  .card.done { opacity: 0.35; }
  .meta { font-size: 0.95rem; margin-bottom: 0.5rem; }
  .issuer { font-weight: 600; }
  .account { color: #444; font-size: 0.85rem; word-break: break-all; }
  .qr { display: flex; justify-content: center; }
  .qr svg { width: 100%; height: auto; max-width: 240px; }
  label.scanned { margin-top: 0.5rem; font-size: 0.85rem; color: #666; user-select: none; }
  details { margin-top: 0.5rem; font-size: 0.75rem; color: #888; }
  details pre { white-space: pre-wrap; word-break: break-all; background: #f0f0f0;
                padding: 0.4rem; border-radius: 6px; }
</style>
<script>
  document.addEventListener("change", e => {
    if (e.target.matches('input[type="checkbox"]')) {
      e.target.closest(".card").classList.toggle("done", e.target.checked);
    }
  });
</script>
</head><body>
<h1>TOTP migration</h1>
<p class="hint">On the new phone open your authenticator app → Add account → Other → scan each QR. Tick the box as you go. <strong>Close this tab when done and delete the file.</strong></p>
<div class="grid">
"""

TAIL = """</div></body></html>
"""


def main(lines: list[str]) -> int:
    cards = []
    for i, raw in enumerate(lines):
        uri = raw.strip()
        if not uri or not uri.startswith("otpauth://"):
            continue
        issuer, account = parse_label(uri)
        try:
            svg = qr_svg(uri)
        except subprocess.CalledProcessError as e:
            print(f"qrencode failed on entry {i}: {e}", file=sys.stderr)
            continue
        cards.append(f"""<div class="card">
  <div class="meta"><div class="issuer">{html.escape(issuer)}</div>
    <div class="account">{html.escape(account)}</div></div>
  <div class="qr">{svg}</div>
  <label class="scanned"><input type="checkbox"> scanned</label>
  <details><summary>show URI</summary><pre>{html.escape(uri)}</pre></details>
</div>""")

    sys.stdout.write(HEAD + "\n".join(cards) + TAIL)
    print(f"rendered {len(cards)} QR code(s)", file=sys.stderr)
    return 0 if cards else 1


if __name__ == "__main__":
    if len(sys.argv) > 1 and sys.argv[1] != "-":
        with open(sys.argv[1]) as f:
            sys.exit(main(f.readlines()))
    else:
        sys.exit(main(sys.stdin.readlines()))

migrate.sh

#!/usr/bin/env bash
# Orchestrate the migration: keychain dump → otpauth URIs → QR-code HTML.
# Writes secrets to $WORK_DIR (default: ~/authenticator-migration), NOT the
# script folder, in case the script folder is cloud-synced.
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORK_DIR="${WORK_DIR:-$HOME/authenticator-migration}"

case "$WORK_DIR" in
  *OneDrive*|*CloudStorage*|*iCloud*|*Dropbox*|*"Google Drive"*)
    echo "error: WORK_DIR ($WORK_DIR) looks cloud-synced — pick a local path." >&2
    exit 1
    ;;
esac

# irestore is installed via `go install` and lands in $GOPATH/bin, which is
# not on PATH by default. Add it so a fresh terminal works without rc edits.
if command -v go >/dev/null; then
  GO_BIN="$(go env GOPATH)/bin"
  case ":$PATH:" in
    *":$GO_BIN:"*) ;;
    *) PATH="$PATH:$GO_BIN" ;;
  esac
fi

missing=()
for cmd in irestore python3 qrencode; do
  command -v "$cmd" >/dev/null || missing+=("$cmd")
done
if (( ${#missing[@]} )); then
  echo "error: missing tool(s): ${missing[*]}" >&2
  echo "  irestore : go install github.com/dunhamsteve/ios/cmd/irestore@latest" >&2
  echo "  qrencode : brew install qrencode" >&2
  echo "  python3  : preinstalled on macOS" >&2
  exit 1
fi

mkdir -p "$WORK_DIR"
chmod 700 "$WORK_DIR"
cd "$WORK_DIR"

echo "==> Available iOS backups (need an *encrypted* one of the source iPhone):"
irestore || true
echo
read -rp "UDID of source iPhone backup: " udid
[[ -n "$udid" ]] || { echo "error: empty UDID" >&2; exit 1; }

echo "==> Dumping keychain (you'll be prompted for the backup password)..."
irestore "$udid" dumpkeys keys.json

echo "==> Extracting otpauth URIs..."
python3 "$SCRIPT_DIR/extract.py" keys.json > otpauth.txt

echo "==> Rendering QR-code page..."
python3 "$SCRIPT_DIR/render_qrs.py" otpauth.txt > qrcodes.html

cat <<EOF

Done. Output in: $WORK_DIR
  keys.json      raw keychain dump (DELETE after migration)
  otpauth.txt    one otpauth:// URI per line (DELETE after migration)
  qrcodes.html   self-contained QR-code page

Next:
  1. open '$WORK_DIR/qrcodes.html'
  2. on the new phone scan each QR with your authenticator app
  3. verify a few generated codes match the source phone
  4. cleanup:  rm -rf '$WORK_DIR'
EOF

Prereqs (one-time)

brew install go qrencode
go install github.com/dunhamsteve/ios/cmd/irestore@latest

Steps

1. Plug the source iPhone into the Mac. In Finder → tick Encrypt local backup, set/remember the password, click Back Up Now. Keychain items are only included in encrypted backups.
2. ./migrate.sh — pick the UDID it prints, enter the backup password.
3. Open ~/authenticator-migration/qrcodes.html on the Mac, scan each QR with your destination authenticator on the new phone. Tick the box as you go.
4. Generate a code on both phones for one or two accounts and verify they match.
5. Clean up: rm -rf ~/authenticator-migration and consider deleting the encrypted backup once the new phone is verified working.

Gotchas worth flagging

• macOS Full Disk Access (FDA) — irestore reads ~/Library/Application Support/MobileSync/Backup, which is TCC-protected. If irestore says operation not permitted, grant FDA to your terminal app in System Settings → Privacy & Security → Full Disk Access, then Cmd-Q and relaunch the terminal (closing the window isn't enough; only newly-launched processes inherit the permission).
• go install binaries land in $(go env GOPATH)/bin, which isn't on PATH by default on macOS. The script adds it automatically; if you run irestore directly elsewhere, add that dir to your PATH.
• Encrypted backup is mandatory — Keychain entries do not appear in unencrypted backups, and the script will report 0 tokens.
• Non-standard parameters (8-digit codes, SHA256, 60-second period) carry through cleanly in the URI; if a destination app rejects one, re-keying that one account at the issuer's site is usually faster than fighting it.
• Whatever destination app you pick, turn on its cloud backup afterwards — the whole point of leaving this app is to not be stuck again on the next phone change. Microsoft Authenticator has iCloud-backed Cloud Backup; Ente Auth and 2FAS have their own E2E-encrypted sync.

Full credit for the underlying decoding logic still goes to @pashky — this is just packaging.