Managing encryption keys

Summary: Back up and restore encryption keys, change keys safely, and resolve key-related build checks.

Save System needs the original encryption key to load an encrypted save. This guide shows you how to back up and restore your keys, and how to change the key used for new saves while keeping older saves readable.

Find your current key

Open Tools › Gley › Save System and select the General tab. The Encryption key section contains two fields:

  • Key ID: a short identifier that helps you match a save or build message to its encryption key. It cannot decrypt a save.
  • Key: your current encryption key, hidden by default. Save System uses this key whenever it writes an encrypted save. Click Show to view its full value or Copy to copy it.
Save System General tab showing Key ID, the masked encryption key, Copy and Manage keys.
General tab: use Copy to back up the current key, or Manage keys… to open the key controls.

Back up your keys

  1. Keep Assets/GleyData/SaveSystem/Resources/SaveSystemSettings.asset in version control and maintain a backup. This file contains the current key and all retained previous keys.
  2. Also keep Assets/GleyData/SaveSystem/Editor/KeyRecord.json in version control when it exists. Save System creates this record during builds to remember which keys earlier builds used.
  3. To keep a separate copy of the current key, open the General tab and click Copy under Encryption key. Store the full copied value somewhere safe.

If you lose an encryption key and have no backup, saves encrypted with that key cannot be recovered. Generating a new key will not restore access to them.

Restore a backed-up key

If your project is missing the key needed to load existing saves, you can restore it from a full key value you backed up earlier. Use the Manage keys section in the Advanced tab to add the key back to your project.

Save System Advanced tab showing Paste key, Apply, a retained Previous keys ID and Regenerate key.
Use Paste key and Apply to restore your backed-up key.
  1. Stop Play mode.
  2. Open Tools › Gley › Save System and click Manage keys… in the General tab.
  3. Paste the full backed-up key into Paste key, then click Apply. Use the full value copied with Copy, not the Key ID.
  4. Enter Play mode and load a save created with that key to confirm it works.
  5. Back up the updated settings file.

The pasted key becomes the current key. The key it replaces and any other retained keys remain under Previous keys. The field accepts a Base64-encoded 32-byte key; copying it from Save System gives you the required format.

Change your encryption key

Suppose players already have saves encrypted with your current key, and you want future saves to use a new key. You do not need to change keys for every update.

  1. Stop Play mode and back up SaveSystemSettings.asset.
  2. Note the current Key ID in the General tab.
  3. Click Manage keys…, then Regenerate key.
  4. When the Regenerate encryption key? confirmation dialog appears, click Regenerate.
  5. Check that the old Key ID appears under Previous keys. Save System keeps that key so existing saves remain readable.
  6. Enter Play mode. Load an existing encrypted save, save it again, then load it once more. Confirm that all three operations succeed. Repeat this test with saves from released versions in a build of your updated game.
  7. Back up the updated SaveSystemSettings.asset and include it in your next build. After building, commit the updated KeyRecord.json to version control.

Changing the key does not modify existing save files. They use the new key the next time they are saved. Keep previous keys so saves created with older keys can still load.

Fix encryption errors when building

Save System checks your encryption keys and settings before building the game. If one of the checks below fails, the build stops and an error appears in Unity’s Console. Follow the instructions for that error, then build again.

A previously shipped key is missing

Console message: starts with This project shipped with key or This project shipped with keys, followed by the missing Key IDs.

Cause: a key recorded by an earlier build is missing from both the current key and Previous keys. The record can include keys used by test builds too.

Fix:

  1. Stop Play mode and note the missing Key IDs in the Console message.
  2. If you want to keep using your current key for new saves, copy its full value from the General tab before restoring other keys.
  3. Find the missing full keys in version control or your backups. Restore a settings file containing all required keys, or follow Restore a backed-up key to apply each missing key.
  4. If you applied keys individually, apply your intended current key last. The other keys remain under Previous keys.
  5. Build again and test loading saves from your released versions.

Generating a new key cannot replace a missing old key. Deleting the key record will not make those saves readable.

The shipped-key record is damaged or unreadable

Console message: starts with The Save System shipped key record and says the file is damaged, or starts with Can’t read the Save System shipped key record. The message includes the file path.

Cause: Save System cannot read KeyRecord.json. The file may be damaged, or a file-access or permission problem may prevent it from being read. Its usual location is Assets/GleyData/SaveSystem/Editor/KeyRecord.json.

Fix:

  1. Check the file path and details in the Console message. If it reports an access or permission problem, resolve that problem first.
  2. If the file is damaged, restore a known-good copy from version control that includes the keys recorded by your earlier builds. If the Console message offers a local backup, you can copy it to the reported record path. The usual backup location is Library/Gley/SaveSystem/KeyRecord.json.bak.
  3. Build again. If a missing-key error appears, follow A previously shipped key is missing.

This restores the history used for build checks. The encryption keys themselves must still be present in SaveSystemSettings.asset.

The settings file is missing

Console message: starts with No Save System settings found, but this project shipped with key or No Save System settings found, but this project shipped with keys.

Cause: the key record shows that earlier builds used encryption keys, but Save System cannot find SaveSystemSettings.asset.

Fix:

  1. Restore SaveSystemSettings.asset from version control or a backup containing all keys used by your released builds. Its usual location is Assets/GleyData/SaveSystem/Resources/SaveSystemSettings.asset.
  2. Build again. If a missing-key error appears, follow A previously shipped key is missing.
  3. Test loading saves from your released versions.

Creating a fresh settings file will not restore the keys needed to load existing encrypted saves.

On This Page