---
description: Secure encryption without hardcoded keys in the code
---

# Encryption

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.

<figure><img src="https://166712561-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fp47l4hoFKIHGBwL1Cm4D%2Fuploads%2FxTtli8WQg6YWkZzc5onr%2Fimage.png?alt=media&#x26;token=ab240f1a-ee5f-4f75-941a-d17c42dc7966" alt=""><figcaption></figcaption></figure>

***

### 📌 Enabling Encryption

To enable encryption for your save files:

1. **Create and open your Save Settings file**:
   * Navigate to:\
     `Create → Crystal Save → Settings → Crystal Save Settings`.
2. **Enable Encryption**:
   * In the **Cryptography Settings** section, tick **Enable Encryption**.
3. **(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.
4. **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:

1. In the Unity Editor Project window, select:
   * `Create → Crystal Save → Settings → Security → Save Encryption Key`.
2.  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.
3. **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.
4. **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.
