Wire Format

Quick Reference#

The format is fixed. It is the one Magic 0.0.41 and earlier wrote, so changing any part orphans every stored value.

Reading a Payload#

MagicEncrypter is the cipher behind both modes. Build one directly when you hold a key that is not app.key:

import 'package:magic_encryption/magic_encryption.dart';

void main() {
  final MagicEncrypter encrypter = MagicEncrypter('0123456789abcdef0123456789abcdef');

  final String payload = encrypter.encrypt('hello');
  final List<String> parts = payload.split(':');

  print(parts.length); // 2: the base64 IV, then the base64 ciphertext
  print(encrypter.decrypt(payload)); // hello
}

MagicEncrypter(String key) throws an Exception unless the key is 32 bytes of UTF-8 (32 characters for ASCII). MagicEncrypter.fromAppKey(String) also accepts a base64: key and throws unless it decodes to 32 bytes. decrypt splits on :, base64-decodes both halves, decrypts and decodes UTF-8 with malformed bytes replaced by U+FFFD.

Not Authenticated#

There is no MAC and no AEAD tag. Two consequences follow:

• CBC is malleable. Someone who can modify a stored payload can flip bits in the IV and flip the same bits in the first plaintext block, predictably. Decryption still succeeds and returns a value the attacker partly chose.
• A decryption failure is observable. A caller that reports it back to whoever supplied the payload builds a padding oracle.

So Crypt keeps a value opaque at rest on the device and is not evidence that the value is unmodified. Verify anything whose integrity matters on the server that issued it, which can hold a secret this layer cannot.

Not Laravel#

Laravel's Crypt writes base64 of a JSON object holding the IV, the value and an HMAC, and refuses a payload whose MAC does not verify. This package writes base64(iv):base64(ciphertext) with no MAC. The two cannot read each other's output, so do not send a Magic payload to a Laravel Crypt::decrypt or the other way round. Exchange data with a server through the transport, not through this cipher.

Gotchas#

Related Documentation#

• Crypt: the facade and its failure modes.
• App Key: producing and formatting the key.
• Testing: pinning an IV to assert an exact payload.