cryptography 2.0.0-nullsafety.0

Cryptographic algorithms for encryption, digital signatures, key agreement, authentication, and hashing. AES, Chacha20, ED25519, X25519, and more. Web Crypto support.

Overview

Popular cryptographic algorithms for Dart / Flutter developers.

This package was developed by Gohilla Ltd (Finland) and open-sourced under the Apache License 2.0.

This package is:

• Easy to use. The API is easy to understand and encourages good defaults.
• Multi-platform. It's easy to customize implementation of X in platform Y.
• Fast. By default, we use platform APIs when available. For example, SHA-512 is over 100 times faster than package:crypto in browsers.

Any feedback, issue reports, or pull requests are appreciated!

Links

• Github project
• Issue tracker
• Pub package
• API reference

Some packages that depend on this

• cryptography_flutter.
  • Android / iOS cryptography support.
• jwk
  • JWK (JSON Web Key) support.
• kms
  • KMS (Key Management Service) support.
• noise_protocol
  • Noise handshake support.

Key concepts

Cryptography implementations

The abstract class Cryptography has factory methods that return implementations of cryptographic algorithms. The default implementation is BrowserCryptography (which works in all platforms, not just browser). You can write your own Cryptography subclass if you need to.

We wrote the following three implementations of Cryptography:

• DartCryptography
  • Gives you implementations written in pure Dart implementations. They work in all platforms.
  • In all platforms supported by Dart, gives you:
    • AesCbc
    • AesCtr
    • AesGcm
    • Blake2b
    • Blake2s
    • Chacha20
    • Chacha20.poly1305Aead
    • Ed25519
    • Hkdf
    • Hmac
    • Pbkdf2
    • Poly1305
    • Sha1
    • Sha224
    • Sha256
    • Sha384
    • Sha512
    • X25519
    • Xchacha20
    • Xchacha20.poly1305Aead
  • SHA1 / SHA2 uses implementation in package:crypto, which is maintained by Google. Relevant parts are copy-pasted to this version because of issue #105 in the original package.
  • The rest of the algorithms in DartCryptography are written and tested by us.
  • Implementations written in pure Dart have been exposed to vastly less testing and review by dedicated specialists in cryptography than platform-provided implementations (in Android, iOS, browsers, etc). That's we highly recommend that you call FlutterCryptography.enable() in the main function of applications.
• BrowserCryptography
  • Extends DartCryptography.
  • Uses Web Cryptography API (crypto.subtle).the
  • In browsers, gives you:
    • AesCbc
    • AesCtr
    • AesGcm
    • Ecdh.p256
    • Ecdh.p384
    • Ecdh.p512
    • Ecdsa.p256
    • Ecdsa.p384
    • Ecdsa.p512
    • Hkdf
    • Hmac
    • Pbkdf2
    • RsaPss
    • RsaSsaPkcs1v15
    • Sha1
    • Sha256
    • Sha384
    • Sha512
• FlutterCryptography
  • A Flutter plugin available in cryptography_flutter.
  • Extends BrowserCryptography.
  • Enabled with FlutterCryptography.enable().
• In Android, gives you:
  • AesCbc
  • AesCtr
  • AesGcm
  • Chacha20
  • Chacha20.poly1305Aead
• In iOS, gives you:
  • AesGcm
  • Chacha20
  • Chacha20.poly1305Aead

Arguments to algorithms

The usual arguments to algorithms are:

• SecretKeyData is used by ciphers, message authentication codes, and KDFs.
• KeyPair and PublicKey are used by key exchange and signature algorithms.
  • SimpleKeyPairData and SimplePublicKey enable to pass octet private/public keys.
  • EcKeyPairData and EcPublicKey enable to pass elliptic curve parameters.
  • RsaKeyPairData and RsaPublicKey enable to pass RSA parameters.
  • For encoding/decoding private/public keys in JWK (JSON Web Key) format, use package:jwk.
  • For encoding/decoding X.509, PKCS12, and other formats, we don't have recommended packages at the moment.
• Nonce ("initialization vector", "IV", or "salt") is a value that does not need to be kept secret. It's required by many algorithms.

Algorithms by type

Ciphers

The following Cipher implementations are available:

• AES
  • AesCbc (AES-CBC)
  • AesCtr (AES-CTR)
  • AesGcm (AES-GCM)
  • Throughputs of the pure Dart implementations are about 50 MB/s, AES-GCM about 5-10 MB/s.
  • Throughputs of the BrowserCryptography implementations are about 400 - 700 MB/s.
• ChaCha20 / XChaCha20
  • Chacha20
  • Chacha20.poly1305Aead (AEAD_CHACHA20_POLY1305)
  • Xchacha20
  • Xchacha20.poly1305Aead (AEAD_XCHACHA20_POLY1305)
  • In our benchmarks, the performance is around:
    • Throughput of the pure Dart implementation is 40 - 140 MB/s in VM.

Digital signature algorithms

The following SignatureAlgorithm implementations are available:

• Ed25519 (curve25519 EdDSA)
  • Performance of the pure Dart implementation is around 200 (signatures or verifications) per second in VM and about 50 in browsers.
• Elliptic curves approved by NIST
  • Ecdsa.p256 (ECDSA P256 / secp256r1 / prime256v1 + SHA256)
  • Ecdsa.p384 (ECDSA P384 / secp384r1 / prime384v1 + SHA384)
  • Ecdsa.p521 (ECDSA P521 / secp521r1 / prime521v1 + SHA256)
  • We don't have implementations of these in pure Dart.
• RSA
  • RsaPss (RSA-PSS)
  • RsaSsaPkcs1v15 (RSASSA-PKCS1v15)
  • We don't have implementations of these in pure Dart.

Key exchange algorithms

The following KeyExchangeAlgorithm implementations are available:

• Elliptic curves approved by NIST
  • Ecdh.p256 (ECDH P256 / secp256r1 / prime256v1)
  • Ecdh.p384 (ECDH P384 / secp384r1 / prime384v1)
  • Ecdh.p521 (ECDH P521 / secp521r1 / prime521v1)
  • We don't have implementations of these in pure Dart.
• X25519 (curve25519 Diffie-Hellman)
  • Throughput of the pure Dart implementation is around 1k key agreements per second (in VM).

Key derivation algorithms

The following implementations are available:

• Hchacha20
• Hkdf (HKDF)
• Pbkdf2 (PBKDF2)

Message authentication codes

The following MacAlgorithm implementations are available:

• Hmac
• Poly1305

Cryptographic hash functions

The following HashAlgorithm implementations are available:

• Blake2b (BLAKE2B)
• Blake2s (BLAKE2S)
• Sha1 (SHA1)
• Sha224 (SHA2-224)
• Sha256 (SHA2-256)
• Sha384 (SHA2-384)
• Sha512 (SHA2-512)

Getting started

In pubspec.yaml:

dependencies:
  cryptography: ^2.0.0-nullsafety.0

Examples

Digital signature

In this example, we use Ed25519.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // The message that we will sign
  final message = <int>[1,2,3];

  // Generate a keypair.
  final algorithm = Ed25519();
  final keyPair = await algorithm.newKeyPair();

  // Sign
  final signature = await ed25519.sign(
    message,
    keyPair: keyPair,
  );
  print('Signature: ${signature.bytes}');
  print('Public key: ${signature.publicKey.bytes}');

  // Verify signature
  final isSignatureCorrect = await ed25519.verify(
    message,
    signature: signature,
  );
  print('Correct signature: $isSignatureCorrect');
}

Key agreement

In this example, we use X25519.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Alice chooses her key pair
  final algorithm = X25519();
  final aliceKeyPair = await algorithm.newKeyPair();

  // Alice knows Bob's public key
  final bobKeyPair = await algorithm.newKeyPair();
  final bobPublicKey = await bobKeyPair.extractPublicKey();

  // Alice calculates the shared secret.
  final sharedSecret = await algorithm.sharedSecretKey(
    keyPair: aliceKeyPair,
    remotePublicKey: bobPublicKey,
  );
  final sharedSecretBytes = await aliceKeyPair.extractBytes();
  print('Shared secret: $sharedSecretBytes');
}

Authenticated encryption

In this example, we encrypt a message with AesCtr and append a Hmac message authentication code.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Choose the cipher
  final algorithm = AesCtr(macAlgorithm: Hmac(Sha256()));

  // Generate a random secret key.
  final secretKey = algorithm.newSecretKey();

  // Generate a random nonce. A nonce is not secret.
  final nonce = algorithm.newNonce();

  // Our message
  final message = utf8.encode('encrypted message');

  // Encrypt
  final secretBox = await algorithm.encrypt(
    message,
    secretKey: secretKey,
    nonce: nonce,
  );
  print('Ciphertext: ${secretBox.cipherText}');
  print('MAC: ${secretBox.mac.bytes}');

  // Decrypt
  final clearText = await algorithm.decrypt(
    secretBox,
    secretKey: secretKey,
    nonce: nonce,
  );
  print('Decrypted: $clearText');
}

Hashing

In this example, we use Sha512.

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

Future<void> main() async {
  // Create a Sha512 sink
  final sink = Sha512().newSink();

  // Add all parts of the authenticated message
  sink.add([1,2,3]);
  sink.add([4,5]);

  // Calculate hash
  sink.close();
  final hash = await sink.hash();

  print('SHA-512 hash: ${hash.bytes}');
}