Skip to content

Backup: Feat - encrypted cloud backup and restore - #2527

Open
gabrielbazan7 wants to merge 1 commit into
bitpay:developfrom
gabrielbazan7:feat/cloud-backup-restore
Open

gabrielbazan7 wants to merge 1 commit into
bitpay:developfrom
gabrielbazan7:feat/cloud-backup-restore

Conversation

@gabrielbazan7

@gabrielbazan7 gabrielbazan7 commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Encrypted backup of the recovery phrase to iCloud (iOS) and Google Drive (Android), and restore from it. TSS keyshares can also be saved to and restored from the cloud.

What the backup file stores

The file is JSON with a plain-text header and an encrypted payload.

  • Header (plain text, authenticated): format, version, key id, key fingerprint, creation time, KDF parameters and salt, cipher and IV. None of these give access to funds.
  • Encrypted payload: the recovery phrase, the key name and, for keys protected with a recovery phrase password (BIP39 passphrase), a flag saying so.

What the file does not store:

  • the BIP39 passphrase (see below);
  • the list of wallets or the wallet service credentials;
  • the xPrivKey or any addresses;
  • labels, notes, contacts or manually added tokens;
  • the app's encryption password.

On restore, wallets are rediscovered from the wallet service, including multisig wallets the key is a copayer of.

Encryption

  • Argon2id (64 MiB, 3 passes, 4 lanes, 16-byte random salt) derives a 32-byte key from the backup password.
  • AES-256-GCM (12-byte random IV) encrypts the payload, with every header field as additional authenticated data.
  • Parsing is strict: exact fields, version 1 only, the KDF parameters must equal the ones the app writes, and both the base64 and the JSON must be canonical. A file can't ask for a different KDF cost.

How it works

Backup (Key Settings → Back Up Recovery Phrase):

  • Opening the backup asks for the app lock: Face ID / fingerprint if biometrics are on, otherwise the PIN. If no lock is set, the app asks to create a PIN first.
  • If the key is encrypted, saving to the cloud also asks for the encryption password (spending password), because the phrase has to be decrypted.
  • Each key has its own backup password. "Back Up Again" asks for that key's password and checks it against that key's newest backup.
  • A new backup password must have 8+ characters, an uppercase letter, a lowercase letter, a number and a symbol. Any non-alphanumeric character counts as a symbol, so the strong password iOS suggests (with hyphens) is accepted.
  • Every backup is a new file, BitPay-Backup-<ms>-<16 hex>.json, in the folder "BitPay Backups":
    • iOS: iCloud container iCloud.com.bitpay.wallet, visible as "BitPay" in iCloud Drive;
    • Android: "My Drive", with the drive.file scope.
  • The app writes the file, reads it back and compares before marking the key as backed up.
  • "Back Up Again" adds a file. "Change Backup Password" adds a file and then deletes the older copies of that key, so the old password no longer opens them.

Restore (Import → Restore from iCloud / Google Drive, or Import → File tab with a downloaded backup file):

  • One row per key. The newest file is tried first; if it can't be opened, older ones are tried.
  • Wrong passwords use the PIN lockout rules: the count persists across launches, is shared by all keys, and the lock escalates 60 s / 300 s / 3600 s.
  • If the key is already on the phone, it isn't imported again: the restore verifies the password, refreshes the balances of all its wallets with the import's progress screens, and opens it. Re-importing would replace the key with the wallets the server returns and could drop local wallets and preferences.
  • If the server finds no wallets for the phrase, the restore shows "No wallets found" instead of creating a key with an empty BTC wallet. The manual phrase import still creates one.

Delete (Key Settings → Delete Key):

  • For a key backed up to the cloud, the person can keep the backup or delete it too.
  • Deleting it asks for Face ID / fingerprint or the PIN when an app lock is set, plus a second confirmation that warns the funds are gone for good without the recovery phrase.
  • If no cloud file is found, the app says so instead of silently deleting only the key.

Keys with a recovery phrase password (BIP39 passphrase)

These keys can now be backed up, but the passphrase is not stored. The backup screen says so.

On restore, "Advanced Options" asks for it, with the same field and text as the manual import. The app checks it against the key fingerprint before importing. If it's missing or wrong, the restore stops and explains why.

TSS keyshares

  • Backup Keyshare now has "Save to iCloud / Google Drive" next to "Save Backup File". It uploads the same encrypted export as the file option (BWC encryptWithPassword, PBKDF2-SHA256, 600,000 iterations), as BitPay-Keyshare-<ms>-<16 hex>.json.
  • The cloud option is hidden when "Do not include private key" is checked.
  • Saving to the cloud requires a strong password, with the same rule as the phrase backup. "Save Backup File" keeps its current rule (required only).
  • Restore lists keyshares as "BitPay Keyshare" and imports them through the existing TSS import (startImportTSSFile). If the TSS key is already on the phone, it's opened instead. The key is identified by the id and fingerprint inside the decrypted keyshare, as the TSS import does, not by the file name.
  • Restore only opens keyshares in the format the app writes (AES-256-GCM, PBKDF2 with 600,000 iterations). A file can't ask for a different cost. Damaged copies are skipped and older ones are tried.
  • Each keyshare backup has its own password too.

Password manager

The backup password fields are declared as new password / password, so the system password manager handles them, as in the design prototype:

  • When the backup password is created, iOS (Passwords / iCloud Keychain) or Android (Google Password Manager) offers to save it.
  • When the app asks for it again ("Back Up Again" or restore), the keyboard suggests it and Face ID or fingerprint fills it in.
  • On a new phone with the same Apple or Google account, it's there too.

The downside: the password ends up in the same account as the file. The BIP39 passphrase field keeps autofill off.

Each key has its own password and the form has no username field. How the password manager labels several saved passwords for the app hasn't been checked on a device yet.

Known limitations and decisions

  • iCloud upload:: after writing the file, the app waits up to 30 s for iOS to report it as uploaded (NSURLUbiquitousItemIsUploadedKey, added to react-native-cloud-storage by patches/react-native-cloud-storage+3.3.0.patch). If iCloud is full the screen says so; if the upload can’t be confirmed in time, the backup fails, the unconfirmed copy is deleted and the key isn’t marked as backed up. On “Change Backup Password”, older copies are deleted only after the new one is confirmed.
  • TSS: if someone keeps two shares of the same TSS wallet (for example two phones of a 2-of-3) in the same iCloud or Google account, that account plus the password is enough to sign. Accepted, not blocked.
  • Deleting a TSS key keeps its keyshare in the cloud.
  • iCloud folder: the "BitPay" folder is public: the files are visible and editable in Files and on iCloud.com. The wrong-password lockout only slows down guesses inside the app; anyone with the file can try passwords elsewhere. What protects the file is Argon2id plus the password rule.
  • Weak password check: the existing isCommonWeakPassword rejects any run of 4 consecutive letters or digits (abcd, 4321), so a password suggested by the system could, rarely, be rejected.
  • App switcher blur: it only applies once onboarding is complete, so the restore screens aren't blurred during onboarding. That condition predates this PR.
  • Change Backup Password deleting older copies departs from "Never overwrite old files": it deletes rather than overwrites, so the old password stops working. If deleting the older copies fails, the screen shows the error even though the new file was saved; "Try Again" saves another file and deletes all the older ones.
  • Deleting the cloud backup from Key Settings isn't in the prototype or the ticket.
  • The manual phrase import still re-imports a key that is already on the phone. That behavior predates this PR.
  • startImportMnemonic now keeps cloudBackupTimestamp when it re-imports an existing key.

@gabrielbazan7
gabrielbazan7 force-pushed the feat/cloud-backup-restore branch 3 times, most recently from 21d68ee to 6925660 Compare November 17, 2026 19:26
@gabrielbazan7
gabrielbazan7 force-pushed the feat/cloud-backup-restore branch from 6925660 to a5a318b Compare November 18, 2026 13:08
@gabrielbazan7
gabrielbazan7 marked this pull request as ready for review November 18, 2026 13:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant