Cryptography for Dart and Flutter

The package provides two main categories of classes to handle cryptographic operations:

1. Native-backed classes (e.g., FlutterChacha20): These attempt to use operating system APIs on Android, iOS, or macOS. If the OS does not support the specific algorithm, they fall back to a background implementation or a pure Dart implementation (from package:cryptography) if available.
2. Background classes (e.g., BackgroundChacha20): These move lengthy computations to a background isolate using Flutter's compute function to prevent UI jank.

Isolate Behavior:

• Small inputs: If the input is very small (e.g., a 16-byte message), computations are performed in the same isolate to avoid the overhead of message passing.
• Large inputs: Extremely large inputs are also computed in the same isolate to avoid the high cost of allocating massive messages across isolates.
• Concurrency: The package uses a queue to prevent memory exhaustion when many requests are sent concurrently.

The package uses several abstraction layers for cryptographic keys. Note that SecretKey and KeyPair instances are opaque and asynchronous by default; they may not be directly readable in memory for security reasons.

Key Abstractions

• SecretKey: Used by ciphers, MACs, and KDFs.
• KeyPair: Used for asymmetric operations. Types include:
  • SimpleKeyPair (e.g., 32-byte Ed25519/X25519 keys)
  • EcKeyPairData (e.g., P-256, P-384, P-521)
  • RsaKeyPairData (RSA private keys)
• PublicKey: Types include:
  • SimplePublicKey (e.g., Ed25519/X25519 public keys)
  • EcPublicKey (e.g., P-256, P-384, P-512)
  • RsaPublicKey (RSA public keys)

Data Access

If a key is accessible in memory, it will be an instance of one of the following data classes:

• SecretKeyData
• SimpleKeyPairData
• EcKeyPairData
• RsaKeyPairData

For encoding/decoding keys in JWK (JSON Web Key) format, use the package:jwk package.

Authenticated encryption requires a SecretKey and an optional nonce (Initialization Vector). If no nonce is provided, one is automatically generated.

Encryption produces a SecretBox containing:

• nonce: The unique byte sequence used.
• cipherText: The encrypted message.
• mac: The Message Authentication Code.

You can use secretBox.concatenation() to combine these parts for transmission.

import 'dart:convert';
import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Choose the cipher
  final algorithm = AesGcm.with256bits();

  // Generate a random secret key.
  final secretKey = await algorithm.newSecretKey();
  final secretKeyBytes = await secretKey.extractBytes();
  print('Secret key: ${secretKeyBytes}');

  // Encrypt
  final secretBox = await algorithm.encryptString(
    'Hello!',
    secretKey: secretKey,
  );
  print('Nonce: ${secretBox.nonce}'); // Randomly generated nonce
  print('Ciphertext: ${secretBox.cipherText}'); // Encrypted message
  print('MAC: ${secretBox.mac}'); // Message authentication code
  
  // If you are sending the secretBox somewhere, you can concatenate all parts of it:
  final concatenatedBytes = secretBox.concatenation();
  print('All three parts concatenated: $concatenatedBytes');

  // Decrypt
  final clearText = await algorithm.decryptString(
    secretBox,
    secretKey: secretKey,
  );
  print('Cleartext: $clearText'); // Hello!
}

Use testCipher to automatically validate that your Cipher implementation complies with API specifications and passes sanity checks (such as decrypt(encrypt(input))) using various inputs.

You can extend these automatic checks by providing custom tests via the otherTests parameter using expectCipherExample to verify specific test vectors.

import 'package:cryptography_test/cryptography_test.dart';
import 'package:cryptography_test/cipher.dart';

void main() {
  testCipher(
    builder: () => MyCipher(someParameter: 123),
    // `testCipher` will do various automatic sanity checks such as:
    //   decrypt(encrypt(input))
    // ...with various interesting inputs.
    //
    // You can give it real test vectors too:
    otherTests: () {
      test('test vector', () async {
        await expectCipherExample(
          clearText: hexToBytes('01 23 45 67 89 ab cd ef'),
          secretKey: hexToBytes('01 23 45 67 89 ab cd ef'),
          nonce: hexToBytes('01 23 45 67 89 ab cd ef'),
          aad: hexToBytes('01 23 45 67 89 ab cd ef'),
          cipherText: hexToBytes('01 23 45 67 89 ab cd ef'),
          mac: hexToBytes('01 23 45 67 89 ab cd ef'),
        );
      });
    },
  );
}