Encryption
Secure encryption without hardcoded keys in the code
Crystal Save supports robust encryption for your serialized save data, ensuring data privacy and integrity across all supported platforms. It uses AES‑256‑GCM, a high-security encryption standard. For platforms like WebGL and Linux, the package automatically falls back to using BouncyCastle, which may slightly increase CPU load during save and load operations.

📌 Enabling Encryption
To enable encryption for your save files:
Create and open your Save Settings file:
Navigate to:
Create → Crystal Save → Settings → Crystal Save Settings
.
Enable Encryption:
In the Cryptography Settings section, tick Enable Encryption.
(Optional) Enable Compression:
You can optionally enable Enable Compression to gzip-compress serialized data before encryption.
Note: Compression reduces file size but will slightly increase CPU load, potentially slowing down save and load operations.
Assign a Save Encryption Key:
Assign a Save Encryption Key asset to the Save Encryption Key field.
If this asset is not provided, encryption remains disabled, even if Enable Encryption is ticked.
What Happens Behind the Scenes: When enabled, Crystal Save automatically generates a unique per-user encryption key from your provided master secret, transparently encrypting save data before storing or uploading it.
🔑 Creating a Save Encryption Key
To create your own encryption key asset:
In the Unity Editor Project window, select:
Create → Crystal Save → Settings → Security → Save Encryption Key
.
Unity will generate a new asset named
StaticMasterSecret
, containing a 32-byte, base-64 encoded secret.Important: This key is generated once upon creation and stored within the asset.
Assign this asset to your Save Settings:
Drag and drop your newly created asset into the Save Encryption Key field of your Save Settings asset.
Secure your encryption key:
Treat this asset as highly confidential. Changing or losing this key will make existing encrypted save files permanently unreadable.
⚙️ Summary of Encryption-Related Options
Here's a quick summary of available encryption options in Crystal Save:
Enable Encryption: Toggles AES‑256‑GCM encryption for your save data.
Enable Compression (Optional): Compresses serialized data with Gzip before encryption to reduce file size, at the expense of increased CPU load and slower save/load times (mainly on WebGL and Linux).
Save Encryption Key: References the
ScriptableObject
containing the 256-bit master secret used to derive per-user encryption keys.
🛠️ Technical Details (Advanced)
Under the hood, Crystal Save uses the following approach for encryption and decryption:
Encryption (
MaybeEncrypt
):Uses a clearly identifiable header (
'CSAV'
) to mark encrypted data.Ensures your data is encrypted transparently, requiring no manual intervention during normal operations.
Decryption (
MaybeDecrypt
):Automatically checks for the presence of the
'CSAV'
header to determine if the data is encrypted.Attempts to decrypt using your provided key. If the key does not match, loading will fail, ensuring data security.
📝 Best Practices
Backup your encryption key asset and store it safely outside your project's repository or publicly accessible locations.
Never share your encryption key publicly or include it in public version control.
Avoid frequent changes to your encryption key once your game is released, as doing so will invalidate users' previous save files.
🚧 Troubleshooting
Save files won’t load after changing encryption keys:
Ensure the encryption key hasn't been changed unintentionally. Once encrypted, files require the same key to decrypt.
Performance slowdowns on WebGL/Linux:
Encryption fallback (BouncyCastle) might slightly increase CPU usage. Consider disabling compression or carefully testing performance on these platforms.
Last updated