Security: Encryption

View raw .md

The Crypt facade encrypts and decrypts text using AES-256-CBC, emitting a compact base64(iv):base64(ciphertext) payload so calling code never handles the underlying cipher details.

On this page

Introduction#

Magic's encrypter provides a simple, convenient interface for encrypting and decrypting text. Each value is encrypted with a fresh random IV and emitted as base64(iv):base64(ciphertext). The payload is not authenticated (there is no MAC or AEAD tag), so it provides confidentiality, not tamper detection: do not treat a successful decrypt as proof of integrity, and do not assume parity with Laravel's Crypt, whose payload format differs.

Magic uses the AES-256-CBC cipher for all encryption operations.

Configuration#

Magic offers two encryption strategies:

Config-Based: Uses the global APP_KEY from your .env or configuration. Useful for server-side compatibility or shared keys.
Device-Based: Uses a unique, randomly generated key stored securely on the user's device via Vault. This is recommended for storing sensitive user data locally.

Using The Encrypter#

Config-Based Encryption#

To encrypt a value using your application's global key:

dart

final secret = Crypt.encrypt('my-secret-value');

To decrypt a value:

dart

try {
  final value = Crypt.decrypt(secret);
} on MagicDecryptException {
  // The value was invalid or corrupted (decryption failed)
}

Device-Based Encryption#

For local data that should only be accessible on the current device, use device-based encryption. This keys is unique per installation.

dart

// Encrypt
final secret = await Crypt.encryptWithDeviceKey('my-user-token');

// Decrypt
final value = await Crypt.decryptWithDeviceKey(secret);

Managing Keys#

You can check if a device-specific key has already been generated:

dart

if (await Crypt.hasDeviceKey()) {
  // Key exists
}

To generate a new device key (Warning: specific to the device encrypter):

dart

// WARNING: This renders previously encrypted data unrecoverable!
await Crypt.generateDeviceKey();

To remove the key entirely:

dart

await Crypt.clearDeviceKey();