Encryption

Secure encryption without hardcoded keys in the code

Crystal Save uses AES-256-GCM to encrypt save data on all supported platforms. On WebGL/Linux it automatically falls back to BouncyCastle, which can add a small CPU cost.

How encryption works

By default, Crystal Save derives a per-user key from:

Master Secret + User Id

This means encrypted saves can only be decrypted when both the master secret and the same user id are available at runtime.

You can optionally disable Use User ID for Encryption to derive a global key (no per-user isolation). See below for trade-offs.

Key source options

You can choose where the master secret comes from at runtime:

1) Static asset (default)

• Uses StaticMasterSecret (ScriptableObject).

• The asset must be included in the build to decrypt local saves.

• Best for offline play and simplest setups.

2) User passphrase

• Uses PassphraseMasterSecretProvider.

• Derives the master secret from a user-provided passphrase (PBKDF2).

• You must prompt for the passphrase before Crystal Save initializes.

• The Salt Base64 stored in the asset is not the passphrase.

• Losing the passphrase means saves are unrecoverable.

Note: The legacy "Server-fetched" key source (client-side) is deprecated. If you need the key to never touch the client, use Cloud Crypto Mode = ServerSide.

Enabling encryption

1. Create Save Settings: Create -> Crystal Save -> Settings -> Crystal Save Settings

2. Enable Encryption in the Cryptography Settings section.

3. Choose Key Source and assign the matching provider asset:

   • Static -> Static Master Secret

   • User Passphrase -> User Passphrase Provider

If no provider is assigned, encryption is disabled even if the toggle is on.

1. (Optional) Choose Cloud Crypto Mode when Cloud Save is enabled:

   • ClientSide (default) -> encrypt/decrypt on the client.

   • ServerSide -> encrypt/decrypt on your server using a Server-Side Crypto Provider.

Use User ID for Encryption (optional)

The Use User ID for Encryption toggle controls whether the user id is part of key derivation.

• ON (default): per-user keys. Best security and isolation.

• OFF: all users share the same derived key. This makes saves portable across installs and Editor/build, but reduces isolation. If the master key leaks, all saves can be decrypted. Not recommended for shared cloud environments.

Important when NOT using authentication

If Unity Authentication is not installed or the player is not signed in, Crystal Save uses a per-install GUID stored in PlayerPrefs as the user id.

Implications:

• Editor saves will not decrypt in a build by default (different user id).

• Reinstalling or clearing PlayerPrefs changes the user id.

• The per-install GUID is not stable: renaming your project/company/product, deleting PlayerPrefs, or changing Persistent Path Mode can change where data is stored or the GUID itself.

• Encrypted saves are not portable across devices without a stable user id.

If you need portability, use Unity Authentication or disable Use User ID for Encryption (with the trade-offs described above).

Runtime requirement

Encrypted saves can only be loaded when the master secret is available at runtime:

• Static key -> included in the build.

• Passphrase -> entered by the user each session (unless stored securely).

• Server-side crypto -> handled by your server; the client does not hold the master key.

Cloud-only storage vs server-side crypto

Crystal Save can run without local disk saves by enabling Cloud Save and setting Keep Local Mirror = false. This is cloud-only storage, but encryption/decryption still happens on the client, so the key must still be available at runtime.

If you need the key to never touch the client, you must move encryption/decryption to the server and use a custom backend/workflow.

Cloud Crypto Mode (Server-side)

When Cloud Save is enabled, you can set Cloud Crypto Mode = ServerSide and provide a Server-Side Crypto Provider. In this mode:

• The client never receives the master key.

• The provider calls your server to encrypt before upload and decrypt after download.

• Keep Local Mirror is ignored to avoid local disk writes.

• You must implement the server endpoints to perform encryption/decryption.

• Server-side crypto applies to save blobs only; slot metadata and screenshots are stored unencrypted.

• Key Source (Static/Passphrase) is ignored because crypto happens on the server.

Server-side key creation (important)

For ServerSide crypto, the master key must live on your server, not in the Unity project or build. The ServerSideCryptoProvider asset only stores endpoint URLs and headers, not the key.

Recommended: generate the key on the server

Create a 32-byte key and store it as a server secret (env var, secret manager, etc.). Example (Linux/macOS):

openssl rand -base64 32

Use the resulting base64 string as your server-side master key.

Alternate (one-time): generate in Unity, then move it

If you want a quick “one-click” start:

1. Open Crystal Save Settings and set Cloud Crypto Mode to ServerSide.

2. Click Export One-Time Server Key (Copy to Clipboard).

3. Paste the copied key into your server’s secret storage.

Warning: If the key ever ships in the build, it defeats the purpose of server-side crypto.

Server endpoint spec (example)

The built-in Server-Side Crypto Provider expects HTTP POST endpoints:

Endpoints are API routes. Do not include the key in the URL path or query. The server should load the key from a secret store.

Encrypt endpoint

• URL: https://your-server.example.com/crystalsave/encrypt

• Request JSON:

  { "base64": "<plaintext_base64>", "userId": "<optional_user_id>" }

• Response (JSON or plain text):

  { "base64": "<encrypted_base64>" }

Decrypt endpoint

• URL: https://your-server.example.com/crystalsave/decrypt

• Request JSON:

  { "base64": "<encrypted_base64>", "userId": "<optional_user_id>" }

• Response (JSON or plain text):

  { "base64": "<plaintext_base64>" }

Headers (optional):

• Authorization: Bearer <unity_access_token>

• X-CrystalSave-UserId: <user_id>

Notes:

• The server must manage the master key and perform crypto.

• The encrypted payload can be any format as long as your encrypt/decrypt endpoints are symmetric.

Minimal Node.js sample (AES-256-GCM)

import express from "express";
import crypto from "crypto";

const app = express();
app.use(express.json({ limit: "10mb" }));

// 32-byte key, base64 in env
const masterKey = Buffer.from(process.env.CS_MASTER_KEY_BASE64, "base64");

function encrypt(plain) {
  const nonce = crypto.randomBytes(12);
  const cipher = crypto.createCipheriv("aes-256-gcm", masterKey, nonce);
  const cipherText = Buffer.concat([cipher.update(plain), cipher.final()]);
  const tag = cipher.getAuthTag();
  return Buffer.concat([nonce, tag, cipherText]).toString("base64");
}

function decrypt(encB64) {
  const data = Buffer.from(encB64, "base64");
  const nonce = data.subarray(0, 12);
  const tag = data.subarray(12, 28);
  const cipherText = data.subarray(28);
  const decipher = crypto.createDecipheriv("aes-256-gcm", masterKey, nonce);
  decipher.setAuthTag(tag);
  return Buffer.concat([decipher.update(cipherText), decipher.final()]);
}

app.post("/crystalsave/encrypt", (req, res) => {
  const b64 = req.body?.base64;
  if (!b64) return res.status(400).json({ error: "missing base64" });
  const plain = Buffer.from(b64, "base64");
  res.json({ base64: encrypt(plain) });
});

app.post("/crystalsave/decrypt", (req, res) => {
  const b64 = req.body?.base64;
  if (!b64) return res.status(400).json({ error: "missing base64" });
  const plain = decrypt(b64);
  res.json({ base64: plain.toString("base64") });
});

app.listen(8080, () => console.log("Crypto server running"));

Minimal ASP.NET Core (C#) sample (AES-256-GCM)

using System.Security.Cryptography;

var app = WebApplication.CreateBuilder(args).Build();

byte[] GetKey()
{
    var b64 = Environment.GetEnvironmentVariable("CS_MASTER_KEY_BASE64") ?? "";
    var key = Convert.FromBase64String(b64);
    if (key.Length != 32) throw new Exception("Invalid key length.");
    return key;
}

app.MapPost("/crystalsave/encrypt", (Payload p) =>
{
    if (string.IsNullOrWhiteSpace(p?.base64)) return Results.BadRequest(new { error = "missing base64" });
    var key = GetKey();
    var plain = Convert.FromBase64String(p.base64);
    var nonce = RandomNumberGenerator.GetBytes(12);
    var cipher = new byte[plain.Length];
    var tag = new byte[16];
    using var aes = new AesGcm(key);
    aes.Encrypt(nonce, plain, cipher, tag);
    var packed = new byte[nonce.Length + tag.Length + cipher.Length];
    Buffer.BlockCopy(nonce, 0, packed, 0, nonce.Length);
    Buffer.BlockCopy(tag, 0, packed, nonce.Length, tag.Length);
    Buffer.BlockCopy(cipher, 0, packed, nonce.Length + tag.Length, cipher.Length);
    return Results.Json(new { base64 = Convert.ToBase64String(packed) });
});

app.MapPost("/crystalsave/decrypt", (Payload p) =>
{
    if (string.IsNullOrWhiteSpace(p?.base64)) return Results.BadRequest(new { error = "missing base64" });
    var key = GetKey();
    var data = Convert.FromBase64String(p.base64);
    if (data.Length < 12 + 16) return Results.BadRequest(new { error = "invalid payload" });
    var nonce = data[..12];
    var tag = data[12..28];
    var cipher = data[28..];
    var plain = new byte[cipher.Length];
    using var aes = new AesGcm(key);
    aes.Decrypt(nonce, cipher, tag, plain);
    return Results.Json(new { base64 = Convert.ToBase64String(plain) });
});

app.Run();

record Payload(string base64, string userId);

Minimal PHP sample (AES-256-GCM)

<?php
header('Content-Type: application/json');

$keyB64 = getenv('CS_MASTER_KEY_BASE64') ?: '';
$key = base64_decode($keyB64, true);
if ($key === false || strlen($key) !== 32) {
  http_response_code(500);
  echo json_encode(['error' => 'invalid key']);
  exit;
}

$body = json_decode(file_get_contents('php://input'), true);
$b64 = $body['base64'] ?? '';
$input = base64_decode($b64, true);
if ($input === false) {
  http_response_code(400);
  echo json_encode(['error' => 'missing base64']);
  exit;
}

if ($_SERVER['REQUEST_URI'] === '/crystalsave/encrypt') {
  $nonce = random_bytes(12);
  $tag = '';
  $cipher = openssl_encrypt($input, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $nonce, $tag);
  $packed = $nonce . $tag . $cipher;
  echo json_encode(['base64' => base64_encode($packed)]);
  exit;
}

if ($_SERVER['REQUEST_URI'] === '/crystalsave/decrypt') {
  if (strlen($input) < 28) {
    http_response_code(400);
    echo json_encode(['error' => 'invalid payload']);
    exit;
  }
  $nonce = substr($input, 0, 12);
  $tag = substr($input, 12, 16);
  $cipher = substr($input, 28);
  $plain = openssl_decrypt($cipher, 'aes-256-gcm', $key, OPENSSL_RAW_DATA, $nonce, $tag);
  echo json_encode(['base64' => base64_encode($plain)]);
  exit;
}

http_response_code(404);
echo json_encode(['error' => 'unknown route']);

Technical details

• Encrypted payloads are tagged with the "CSAV" header.

• AES-256-GCM is used where available.

• Master secret must be exactly 32 bytes (base64 encoded in assets).

Best practices

• Back up the master secret asset and keep it out of public repos.

• Do not rotate the master secret after release unless you accept save loss.

• Prefer Unity Authentication when you want cross-device save portability.

• For editor-to-build testing, disable encryption or ensure a stable user id.

Troubleshooting

• "Save file was encrypted with a different master secret" -> master secret or user id changed.

• Encrypted saves fail after reinstall -> PlayerPrefs GUID changed.

• Performance issues on WebGL/Linux -> consider disabling compression.