Backup Encryption

Since version 1.8.0 every backup is encrypted before it leaves your server. This page explains, step by step, how to create your encryption key, enter it in the admin, test it and keep it safe. Plan about 15 minutes.

The short version: the key consists of two parts. The public key (age1…) goes into the admin; the shop can only lock backups with it. The private key (AGE-SECRET-KEY-1…) stays with you; only it can unlock them. Keep the private key in two places, never on the server. Without it, no backup can ever be restored, by you or anyone else.

---

How it works

	Public key age1…	Private key AGE-SECRET-KEY-1…
What it does	Encrypts (locks) the backups	Decrypts (unlocks) the backups
Where it goes	Into the admin (Settings → Export & Backups → Encryption)	Your password manager and a USB stick (or another offline place)
Secret?	No: anyone may see it, it can only lock	Yes. Whoever has it can read all your backups
If lost	Print it again from the key file (see below)	The backups made for it can't be opened any more. Create a new key right away

The shop uses age, a small, free and widely used encryption tool. The shop only ever knows the public key, so it can encrypt but never decrypt: someone who gets hold of your GitHub token, your GitHub account or even the whole server still can't read a single backup. Backups are only uploaded encrypted. Without a public key, no backup is made.

---

Step 1 — Install age on your own computer

Not on the server: the private key will be created on your computer and must never be on the server.

Windows

1. Open PowerShell: press the Windows key, type PowerShell, press Enter.
2. Run:

   winget install FiloSottile.age

3. Close PowerShell and open a new window (otherwise it doesn't find the new program yet).
4. Check:

   age --version

   It prints a version number, e.g. v1.2.1.

No winget? Download age-…-windows-amd64.zip from github.com/FiloSottile/age/releases, unpack it, and run the commands below from the unpacked folder (.\age.exe, .\age-keygen.exe).

macOS

1. Open Terminal (Spotlight: Terminal).
2. Install Homebrew if you don't have it, then:

   brew install age
   age --version

Linux

sudo apt install age        # Debian / Ubuntu
sudo dnf install age        # Fedora
age --version

---

Step 2 — Create the key pair

Create it in a temporary place you'll clean up, not in a project or Git folder (a file there can end up in a commit by accident). Your home folder is fine for now; in Step 5 the file is moved to its safe places.

Windows (PowerShell):

cd $HOME
age-keygen -o shop-backup-key.txt

macOS / Linux:

cd ~
age-keygen -o shop-backup-key.txt

It prints one line:

Public key: age1qz3k…(62 characters in total)

That is your public key. The file shop-backup-key.txt now holds the private key. It looks like this (don't share yours with anyone):

# created: 2026-11-02T10:15:00+01:00
# public key: age1qz3k…
AGE-SECRET-KEY-1…

Lost the line with the public key? It's in the file after # public key:, or print it again at any time:

age-keygen -y shop-backup-key.txt

Several people or a second computer need to restore backups? They all use this one key file (copy it securely, see Step 5). Want a separate emergency key instead? See A second key for emergencies.

---

Step 3 — Enter the public key in the admin

1. Log in to the admin as a superadmin.
2. Settings → Export & Backups → box Automatic Backups to GitHub → section Encryption.
3. Paste the line Public key: age1… into Your public key. The whole line is fine; the shop picks out the key. Below the field it says 1 public key recognized (not saved yet).
4. Leave the page open for Step 4.

Pasted the private key or the whole file by mistake? The field is cleared at once and a red notice explains it. The key was not sent to the shop. Paste only the Public key: age1… line.

---

Step 4 — Test the key

This proves that your private key really opens the backups, before you ever need it. Your private key stays on your computer; the test happens there.

1. In the admin, click Test the key. Your browser downloads a small file backup-key-test.txt.age.

2. Open it with your private key. Go to the folder the file was downloaded to, and give the full path to your key file:

   Windows (PowerShell), key file from Step 2 in your home folder:

   cd $HOME\Downloads
   age -d -i $HOME\shop-backup-key.txt backup-key-test.txt.age

   macOS / Linux:

   cd ~/Downloads
   age -d -i ~/shop-backup-key.txt backup-key-test.txt.age

3. It prints:

   It works!
   
   Your private key opens the backups of <your shop name>.
   …
   

Message	Meaning
It works!	Everything is right. Continue with Step 5
failed to open file … The system cannot find the file specified	age doesn't find the key file at that path. Check the path after -i (tip: drag the file into the PowerShell/Terminal window to paste its full path)
no identity matched any of the recipients	The public key in the admin does not belong to this key file. Copy the public key again (age-keygen -y …) and paste it into the admin
age: command not found / not recognized	age is not installed, or PowerShell was not reopened after installing (Step 1)

4. Back in the admin, click Save backup settings, then Back up now. On GitHub, in your backup repository under Releases, the new backup ends in .zip.age.

Delete the test file afterwards: it contains nothing secret, it's only for the test.

---

Step 5 — Keep the private key safe (two places)

The key file must exist in two places, neither of them the shop server. One copy alone is a single point of failure: a broken laptop, a lost password-manager login or a server crash must not take the only copy with it.

Place 1: your password manager

Most password managers (Bitwarden/Vaultwarden, 1Password, KeePassXC, Proton Pass …) can store it in one of two ways:

• As a file attachment (best): create an entry "Shop backup key" and attach shop-backup-key.txt.
• As a secure note: open shop-backup-key.txt in a text editor (Windows: notepad $HOME\shop-backup-key.txt), copy all three lines into the note. To use it later, paste them back into a file named shop-backup-key.txt.

Does your password manager run on the same server as the shop (e.g. a self-hosted Vaultwarden)? Then it doesn't count as a second place on its own: if that server is lost, both are gone. Place 2 matters even more then.

Place 2: offline, e.g. a USB stick

Copy shop-backup-key.txt to a USB stick and keep it somewhere safe (a drawer at home, a safe). Alternatively print the file and keep the paper in a safe place (to use it, type the AGE-SECRET-KEY-1… line into a file again).

Remove it from your computer

Once both copies exist and you've checked that you can open them:

Windows: Remove-Item $HOME\shop-backup-key.txt and empty the recycle bin if you deleted it in Explorer. macOS / Linux: rm ~/shop-backup-key.txt

Also delete any other copy you made by accident (e.g. in a project folder or in Downloads). The shop's Git repository ignores files named *backup-key*.txt, but a key file has no business in any project folder.

Never

• upload the private key to the shop, to GitHub or to any cloud folder that isn't encrypted,
• send it by e-mail or chat,
• store it on the shop server.

---

Using the key for a restore

You only need the private key when you restore a backup (see Restoring a Backup):

1. Get the key file from your password manager or USB stick onto your computer (save it as shop-backup-key.txt).
2. In the admin: Settings → Export & Backups → Restore a Backup, choose the backup, then under Private key of the backups choose the key file (or paste the AGE-SECRET-KEY-1… line). The key is only used for that restore; it is never saved or logged.
3. Delete the key file from your computer again afterwards.

Without the admin (command-line restore), decrypt the backup on your computer first:

age -d -i /path/to/shop-backup-key.txt -o shop-backup-20261102-020000.zip shop-backup-20261102-020000.zip.age

and continue with Restoring a Backup#restoring-on-the-command-line.

---

A second key for emergencies

You can enter several public keys, one per line. Every backup is then encrypted to all of them, and each matching private key opens it on its own. Useful for an emergency key that lives somewhere else entirely (a safe, a trusted person):

1. Create a second key pair exactly as in Step 2, with another name: age-keygen -o shop-backup-key-emergency.txt.
2. Paste both Public key: age1… lines into the admin, one per line. It shows 2 public keys recognized.
3. Test the key checks both at once: the test file opens with either private key.
4. Keep the emergency key file in its own two places.

---

Changing the key

Change it when the private key may have been seen by someone else, or when you replace it with a new one:

1. Create a new key pair (Step 2) and test it (Step 4).
2. Replace the public key in the admin and save. The admin asks for confirmation first.
3. Keep the old key file as long as backups made with it are still on GitHub (with 30 daily backups: one month). Those backups can still only be opened with the old private key. If the old key was exposed, delete those old backups on GitHub (repository → Releases → each old backup → Delete) instead.

Lost the private key?

Then the backups encrypted with it can't be opened, by anyone. Nobody can recover it, not even the RustCraft developers; that is the point of the encryption. Do this right away:

1. Create a new key pair (Step 2), enter it in the admin and test it (Steps 3–4).
2. Click Back up now. From now on you have restorable backups again.
3. Keep the new key in two places this time (Step 5).

---

Questions

Can I use the same key for several shops? Yes: enter the same public key in each shop. One private key then opens the backups of all of them. Separate keys per shop keep them independent; both work.

Does the key ever expire? No. Unlike the GitHub token, an age key works forever.

Are old, unencrypted backups encrypted later? No. Backups made before version 1.8.0 stay unencrypted .zip files on GitHub until they are rotated out (or you delete them there). See Backups#coming-from-a-version-before-180.

Why age and not a password? A password would have to be stored on the server for automatic backups, which is exactly what the encryption should protect against. With age, the server only has the public key, which can't decrypt anything.