Security: Encryption

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.

• Introduction
• Configuration
• Using The Encrypter
  • Config-Based Encryption
  • Device-Based Encryption
• Managing Keys

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:

1. Config-Based: Uses the global APP_KEY from your .env or configuration. Useful for server-side compatibility or shared keys.
2. 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:

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

To decrypt a value:

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.

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

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

[!IMPORTANT] Device-based encryption is asynchronous (Future) because it retrieves the key from secure storage.

Managing Keys

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

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

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

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

To remove the key entirely:

await Crypt.clearDeviceKey();