cryptography 0.3.0

Popular cryptographic algorithms. Enables you to do key agreement, digital signature, encryption, message authentication, and hashing.

Overview

Popular cryptographic algorithms implemented in Dart.

Copyright 2020 Gohilla Ltd. Licensed under the Apache License 2.0.

Links

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

Some things to know

• SHA1 and SHA2 implementations use package:crypto. It's maintained by Google, but unfortunately didn't cover some algorithms we needed.
• We wrote pure Dart implementations for X25519, Chacha20 family, HKDF, HMAC, Poly1305, and Blake2S.
• We wrote support for automatic use of Web Cryptography API (NIST elliptic curves, AES) in browsers.
• AES in non-browsers is implemented with package:pointycastle, an MPL 3.0 licensed package derived from Bouncy Castle. We may eliminate the dependency at some point.
• The APIs generally include both asynchronous and synchronous methods (for instance, sharedSecret(...) and sharedSecretSync(...)). We recommend that you use asynchronous methods because they are able to take advantage of asynchronous platform APIs such as Web Cryptography API.

Used by

• kms
  • A Dart package for hardware-based or cloud-based key management solutions.
• Add your project here?

Want to contribute?

• We recommend that you start by creating an issue in the issue tracker.

Available algorithms

Key exchange algorithms

• NIST curves
  • ecdhP256 (ECDH P256 / secp256r1)
  • ecdhP384 (ECDH P384 / secp384r1)
  • ecdhP521 (ECDH P521 / secp521r1)
  • Currently only supported in browsers (Web Cryptography API).
• x25519
  • X25519 (curve25519-based Diffie-Hellman) has been adopted by technologies such as SSH, TLS, Signal, WhatsApp, and Wireguard. Performance of our Dart implementation is about 1k exchanges per second on a Macbook Pro.

For more more documentation, see KeyExchangeAlgorithm.

Digital signature algorithms

• NIST curves
  • ecdsaP256Sha256 (ECDSA P256 / secp256r1 with SHA256)
  • ecdsaP384Sha256 (ECDSA P384 / secp384r1 with SHA256)
  • ecdsaP521Sha256 (ECDSA P521 / secp521r1 with SHA256)
  • Currently only supported in browsers (Web Cryptography API).
• ed25519

For more more documentation, see SignatureAlgorithm.

Ciphers

• AES
  • aesCbc (AES-CBC)
  • aesCtr32 (AES-CTR, 96-bit nonce, 32-bit counter)
  • aesGcm (AES-GCM)
    • Currently only supported in browsers (Web Cryptography API).
• Chacha20 family
  • chacha20
  • chacha20Poly1305Aead (AEAD_CHACHA20_POLY1305)
  • Chacha20 is a symmetric encryption algorithm that's simpler than AES and tends to perform better than the latter in CPUs that don't have AES instructions. The algorithm has been adopted by technologies such as TLS, SSH, Signal, and Wireguard. Performance of our Dart implementation is about 50-100MB/s on Macbook Pro.

For more more documentation, see Cipher.

Key derivation algorithms

• Hkdf

Message authentication codes

• Hmac
• poly1305
  • The current implementation uses BigInt instead of optimized 128bit arithmetic, which is a known issue.

For more more documentation, see MacAlgorithm.

Cryptographic hash functions

• blake2s (BLAKE2S)
• sha1 (SHA1)
• sha224 (SHA2-224)
• sha256 (SHA2-256)
• sha384 (SHA2-384)
• sha512 (SHA2-512)

For more more documentation, see HashAlgorithm.

Getting started

1. Add dependency

dependencies:
  cryptography: ^0.3.0

2. Use

Encryption

In this example, we use chacha20.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Generate a random 256-bit secret key
  final secretKey = await chacha20.newSecretKey();

  // Generate a random 96-bit nonce.
  final nonce = chacha20.newNonce();

  // Encrypt
  final result = await chacha20Poly1305Aead.encrypt(
    [1, 2, 3],
    secretKey: secretKey,
    nonce: nonce, // The same secretKey/nonce combination should not be used twice
    aad: const <int>[], // You can include additional non-encrypted data here
  );
  print('Ciphertext: ${result.cipherText}');
  print('MAC: ${result.mac}');
}

Key exchange

In this example, we use x25519.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Let's generate two keypairs.
  final localKeyPair = await x25519.newKeyPair();
  final remoteKeyPair = await x5519.newKeyPair();

  // We can now calculate a shared secret
  var secretKey = await x25519.sharedSecret(
    localPrivateKey: localKeyPair.privateKey,
    remotePublicKey: remoteKeyPair.publicKey,
  );
}