AmberHush

Open AmberHush backups with DotBGE or bge

AmberHush photos and backups use the open BGE3 format, so they aren’t locked into the app. With a complete backup and a matching credential, you can open your photos on a Mac or Linux computer with the free bge command-line tool. All decryption happens on your computer.

Updated October 9, 2026 · Current backup format: schema 3 · Commands checked with bge 0.1.1

1. What you need

  • The complete backup folder made in AmberHush, including manifest.json and objects/. A recovery code or exported private key alone contains no photos. An iPhone system backup is restored through iOS first.
  • One way to open the library: the master password used for this backup, its matching recovery code, or the private key file exported in AmberHush and its password. If the vault is protected by your iPhone passcode, use a recovery code or the exported private key: Face ID and the iPhone passcode do not open a backup in bge.
  • A computer you trust, with enough free space for the decrypted files.

Install the free bge tool for macOS or Linux. On macOS you can also use Homebrew:

brew install --cask dotbge/tap/bge
bge --version

Work on a copy of the backup. Create a separate working folder and open Terminal in that folder. The commands below use files you copy into it; they never require changing the original backup. At -p, enter the password when the tool prompts, not in the command itself.

The resulting PEM keys, file list, photos and videos are decrypted files. Keep them in a protected location, do not upload them to this website or send them to support, and remove temporary keys when finished. Save or print this page to keep an offline copy of the instructions.

2. Find the actual files

Open manifest.json in a text editor. For schema 3, keys lists the library’s key files. Find the entry whose path ends in the file you need, such as /identity.password.bge.

path is a logical name, not the file’s location in the backup. Its objectName gives the actual filename. Look inside objects/, in the folder named by that filename’s first two characters. For example, an objectName beginning with ab is at objects/ab/<the complete objectName>. If it is not there, check directly in objects/ for an older flat-layout object.

Copy that object to your working folder and rename only the copy to the name used below, such as identity.password.bge. Repeat this lookup for each required file. You can check the object’s SHA-256 against the entry’s sha256 using shasum -a 256 on macOS or sha256sum on Linux.

3. Open the library key

Use one of the following paths. Each produces library-key.pem; use a fresh working folder when trying another path so an existing output is not overwritten.

With a master password

Locate and copy identity.password.bge from keys, then enter the master password that was in use when this backup was made.

bge decrypt identity.password.bge -p -o library-key.pem

With a recovery code

Locate and copy both recovery.private.bge and identity.recovery.bge from keys. Enter the recovery code for this backup exactly as printed: uppercase, including hyphens. A newer code may not open an older backup.

bge decrypt recovery.private.bge -p -o recovery-key.pem
bge decrypt identity.recovery.bge -k recovery-key.pem -o library-key.pem

With an exported private key

In AmberHush, Settings › Advanced › Export Private Key saves AmberHush_key_backup.bge: the key backup format DotBGE uses, protected by the password you chose. It is a separate file, not part of the backup. Copy it into your working folder and enter that password. The result is JSON whose privateKeyPEM field is the library key; save that field as library-key.pem:

bge decrypt AmberHush_key_backup.bge -p -o key-backup.json
plutil -extract privateKeyPEM raw -o library-key.pem key-backup.json

plutil comes with macOS. On Linux, use jq -r .privateKeyPEM key-backup.json > library-key.pem. The JSON’s keyID matches the Key ID in AmberHush’s Settings › Advanced. Delete key-backup.json when finished; it contains the private key.

If you use DotBGE, you can import the same file there with Import Key Backup and open files encrypted for this vault in DotBGE. The exported key covers only the library; each private space has its own key (step 6).

4. Open the encrypted file list

Back in manifest.json, find list.objectName. Locate that object as in step 2, copy it into your working folder as list.bge, and decrypt it:

bge decrypt list.bge -k library-key.pem -o file-list.json

Open file-list.json. Its files entries map each logical path to an objectName. The top-level vaultID identifies the main library’s space. Follow this list instead of decrypting every object: the backup may also retain older objects that are no longer in the latest list.

5. Decrypt photos and videos

Find entries under spaces/<vaultID>/media/. Locate an object as in step 2 and copy it as selected-media.bge. Inspect its encrypted metadata to see its original name and type, then choose a suitable output name:

bge inspect selected-media.bge -k library-key.pem
bge decrypt selected-media.bge -k library-key.pem -o recovered-photo.heic

recovered-photo.heic is an example: choose .jpg, .mov, .mp4 or another extension that matches the file. The tool does not automatically use the original name from metadata. Repeat for the resources you need; thumbnails are separate resources and a Live Photo has both a still image and a movie. Keep both halves.

Older media may have no filename metadata. Its encrypted catalog records originalFilename, resource roles, album membership and capture details. The catalog entries are listed under spaces/<vaultID>/catalog/ and decrypt with the same key. Reconstructing the current catalog requires the latest valid snapshot and the following journal entries; use the notes below. The steps above recover individual files, not a ready-made Apple Photos library.

Read filenames and resource roles from an older catalog

Locate a catalog entry in file-list.json, copy its object as catalog-entry.bge, then open it with the corresponding space key:

bge decrypt catalog-entry.bge -k library-key.pem -o catalog-entry.json

Look for the media’s logical filename (the UUID filename from its path, not its hashed objectName) in a resource’s encryptedFilename. That resource records originalFilename, uniformTypeIdentifier and role; sourceSHA256 lets you check the decrypted bytes. A thumbnail is not the full-resolution photo. The containing asset records its capture details and album IDs.

For the current catalog state, start with the highest-numbered valid snapshot-….bge. Its JSON has sequence, lastEntryHash, assets and albums. Then apply entries under catalog/journal/ with higher sequence numbers, in order. The first entry after a snapshot must have previousHash equal to the snapshot’s lastEntryHash; each subsequent entry must reference the SHA-256 of the preceding plaintext JSON bytes, without reformatting them. Entries contain operation and its fields; a batch applies its changes in order. If no snapshot exists, start at journal sequence 1. A gap, hash mismatch or unreadable required entry means the current metadata cannot be fully reconstructed; individual intact media files can still be decrypted.

6. Private spaces need their own key

The library key opens the schema 3 file list, but it cannot decrypt a private space’s media. First open the list as above using a library credential. Then find the chosen private space’s spaces/<space ID>/ entries. Keep each space’s working files in a separate folder. If you do not know the space ID, try your private-space password against each candidate’s password wrapper, using a new output name each time. Only a matching password opens it.

With that space’s password, copy its identity.password.bge as private-identity.password.bge and a media object as private-media.bge. Replace the output extension as appropriate:

bge decrypt private-identity.password.bge -p -o private-key.pem
bge inspect private-media.bge -k private-key.pem
bge decrypt private-media.bge -k private-key.pem -o recovered-private-photo.heic

If recovery was enabled for that space in this backup, use the recovery-key.pem obtained from the library’s recovery.private.bge in step 3. The private space has its own identity.recovery.bge, but does not have a separate recovery.private.bge. Copy its wrapper as private-identity.recovery.bge and copy the recovery key into this working folder:

bge decrypt private-identity.recovery.bge -k recovery-key.pem -o private-key.pem

Use the resulting private-key.pem for that space’s media. The recovery path must have been enabled for this space and match the recovery key in this backup. If a code change had not yet updated the private space, use its password or the matching recovery files from an older backup.

7. Older backups

In schema 1 and 2, manifest.json.files is already the file list; there is no encrypted list to open. Locate the key and media entries there. Schema 1 objects may be directly in objects/. Early backups that lack recovery.private.bge require the original recovery-kit folder containing that file; the recovery code alone cannot replace it.

8. If a step fails

  • File not found: check objectName, the two-character folder, and whether the backup was fully copied. Logical path names are not on-disk paths.
  • Cannot decrypt: check the backup date, the matching password/code/key, and the object’s hash. This can also mean damaged ciphertext.
  • Output already exists: choose a new output name or working folder; keep your existing files.
  • Unsupported format: update bge. Do not edit the version or ciphertext.

If all usable credentials are lost, neither this guide nor the developer can recover the keys. For questions about the procedure, contact support without sending credentials or private files.