Skip to main content

Backup & Restore

Overview​

AVTotpy supports exporting all your TOTP codes to an encrypted backup file and restoring them from it. This is useful for migrating to a new instance, recovering from data loss, or keeping an offline copy of your codes in untrusted places.

The backup file is encrypted and bound to the user who created it: only the same user, with the same server encryption secret, can import it back.

Exporting codes​

Click on the Export codes icon on the top right and then on the Export encrypted backup link. The browser will download a binary .avtotpy backup file containing all your TOTP codes encrypted.

info

If you have no codes, the downloaded file is still valid — it is simply an empty backup.

Importing codes​

Click on the Import codes icon on the top right, then upload the .avtotpy backup file produced during export. On success you are redirected to a confirmation page; on failure the page reports that the import was rejected.

Import is additive: existing codes are kept. Any code in the backup file that is not already present is added.

Codes that already exist in your account are duplicated.

caution

The backup file can only be imported by the same user who exported it. Attempting to import a file belonging to a different user will fail. The at-rest encryption key MUST also be the same.

How it works​

The backup format is a self-contained binary blob with the following layout:

magic (20 bytes) | version (2 bytes) | salt (16 bytes) | encrypted payload
  • Magic: a fixed marker used to identify valid AVTotpy backup files and reject arbitrary uploads quickly.
  • Version: the backup format version, used for forward compatibility.
  • Salt: 16 random bytes generated at export time, used in key derivation. Each export produces a different salt, so two exports of identical data produce different files.
  • Encrypted payload: the TOTP codes serialised as JSON and encrypted using AES-GCM-SIV via the versioned encryption scheme described in Security.

Key derivation​

The encryption key for the backup payload is derived from the following fields:

  • the server encryption secret (TOTP_ENCRYPTION_SECRET_BASE64)
  • the username of the authenticated user

Binding the key to the username means that a backup file is cryptographically tied to the user who created it. Importing it under a different username produces a decryption failure even if the server secret is the same.