cryptography 0.3.1

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

Used by

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

Want to contribute?

• Any help is appreciated! We recommend that you start by creating an issue in the issue tracker.

Some things to know

• SHA1 and SHA2 implementations use package:crypto, which is maintained by Google. It's very limited so we decided to write this package.
• We wrote pure Dart implementations for X25519, Chacha20 family, AES-CBC, AES-CTR, HKDF, HMAC, Poly1305, and Blake2s. We also added support for use of Web Cryptography API (NIST elliptic curves, AES) in browsers.
• 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.

Available algorithms

Key exchange algorithms

• NIST elliptic 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) is our recommendation for new applications. It's used in 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 elliptic 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
  • ED25519 (curve25519-based EdDSA) is our recommendation for new applications. Performance of our Dart implementation is about 10 verifications per second. It has a lot low-hanging fruits for optimization.

For more more documentation, see SignatureAlgorithm.

Ciphers

• AES
  • aesCbc (AES-CBC)
  • aesCtr (AES-CTR)
  • aesGcm (AES-GCM)
    • Currently only supported in browsers (Web Cryptography API).
• Chacha20 family
  • chacha20
  • chacha20Poly1305Aead (AEAD_CHACHA20_POLY1305)
  • xchacha20
  • xchacha20Poly1305Aead (AEAD_XCHACHA20_POLY1305)
  • Chacha20 (AEAD) is our recommendation for new applications. It's used in technologies such as TLS, SSH, Signal, and Wireguard. Performance of our Dart implementation is about 50-100MB/s on a Macbook Pro.

For more more documentation, see Cipher.

Key derivation algorithms

• Hkdf

Message authentication codes

• Hmac
• poly1305

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.

Adding dependency

In pubspec.yaml:

dependencies:
  cryptography: ^0.3.1

Examples

Key agreement with X25519

In this example, we use x25519.

import 'package:cryptography/cryptography.dart';

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

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

  print('Shared secret: ${secretKey.bytes}');
}

Digital signature with ED25519

In this example, we use ed25519.

import 'package:cryptography/cryptography.dart';

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

  // Generate a random ED25519 keypair
  final keyPair = await ed25519.newKeyPair();

  // Sign
  final signature = await ed25519.sign(
    message,
    keyPair: keyPair,
  );

  print('Signature: ${signature.bytes}');
  print('Public key: ${signature.publicKey.bytes}');

  // Verify signature
  final isVerified = await ed25519.verify(
    message,
    signature: signature,
  );

  print('Correct signature: $isVerified');
}

Authenticated encryption with Chacha20 + Poly1305

In this example, we use chacha20Poly1305Aead.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Choose the cipher
  final cipher = chacha20Poly1305Aead;

  // Choose some 256-bit secret key
  final secretKey = SecretKey.randomBytes(32);

  // Choose some unique (non-secret) 96-bit nonce.
  // The same (secretKey, nonce) combination should not be used twice!
  final nonce = Nonce.randomBytes(12);

  // Our message
  final message = <int>[1, 2, 3];

  // Encrypt
  final encrypted = await cipher.encrypt(
    message,
    secretKey: secretKey,
    nonce: nonce,
  );

  print('Encrypted: $encrypted');

  // Decrypt
  final decrypted = await cipher.decrypt(
    encrypted,
    secretKey: secretKey,
    nonce: nonce,
  );

  print('Decrypted: $decrypted');
}

Authenticated encryption with AES-CTR + HMAC-SHA256

In this example, we use aesCtr and Hmac.

import 'package:cryptography/cryptography.dart';

Future<void> main() async {
  // Choose the cipher
  final cipher = CipherWithAppendedMac(aesCtr, Hmac(sha256));

  // Choose some 256-bit secret key
  final secretKey = SecretKey.randomBytes(16);

  // Choose some unique (non-secret) nonce (max 16 bytes).
  // The same (secretKey, nonce) combination should not be used twice!
  final nonce = Nonce.randomBytes(12);

  // Our message
  final message = <int>[1, 2, 3];

  // Encrypt
  final encrypted = await cipher.encrypt(
    message,
    secretKey: secretKey,
    nonce: nonce,
  );

  print('Encrypted: $encrypted');

  // Decrypt
  final decrypted = await cipher.decrypt(
    encrypted,
    secretKey: secretKey,
    nonce: nonce,
  );

  print('Decrypted: $decrypted');
}

Message authentication with HMAC-BLAKE2S

In this example, we use Hmac and blake2s.

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

Future<void> main() {
  // Choose a secret key
  final secretKey = SecretKey(utf8.encode('qwerty'));

  // Create a HMAC-BLAKE2S sink
  final macAlgorithm = const Hmac(blake2s);
  final sink = macAlgorithm.newSink(secretKey: secretKey);

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

  // Calculate MAC
  sink.close();
  final macBytes = sink.mac.bytes;

  print('Message authentication code: $macBytes');
}