better_cryptography

Description:

better cryptography

Overview #
Popular cryptographic algorithms for Dart / Flutter
developers.
Maintained by Gohilla Ltd. Licensed 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 #

better_cryptography_flutter.

Android / iOS cryptography support.


better_jwk

JWK (JSON Web Key) support.



Key concepts #
Key classes #
The usual arguments to algorithms are:

SecretKeyData
is used by ciphers, message authentication codes, and key derivation functions.
KeyPair and
PublicKey
are used by key exchange and signature algorithms.

SimpleKeyPairData
and SimplePublicKey
are used when keys are simple byte sequences.
EcKeyPairData
and EcPublicKey
are used by P-256 / P-384 / P-512 algorithms.
RsaKeyPairData
and RsaPublicKey
are used by RSA algorithms.
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.



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)
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 1000 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)

Available 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.
SHA1 / SHA2 uses implementation in package:crypto, which
is maintained by Google. The rest of the algorithms in DartCryptography are written and tested by us.
DartCryptography gives:

AesCbc
AesCtr
AesGcm
Blake2b
Blake2s
Chacha20
Chacha20.poly1305Aead
Ed25519
Hkdf
Hmac
Pbkdf2
Poly1305
Sha1
Sha224
Sha256
Sha384
Sha512
X25519
Xchacha20
Xchacha20.poly1305Aead




BrowserCryptography

Extends DartCryptography.
Uses Web Cryptography API (crypto.subtle).the
In browsers, BrowserCryptography gives:

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, FlutterCryptography gives:

AesCbc
AesCtr
AesGcm
Chacha20
Chacha20.poly1305Aead


In iOS, FlutterCryptography gives:

AesGcm
Chacha20
Chacha20.poly1305Aead





Getting started #
In pubspec.yaml:
dependencies:
cryptography: ^2.0.5
copied to clipboard
If you use Flutter, we recommend that you also add cryptography_flutter:
dependencies:
cryptography: ^2.0.5
cryptography_flutter: ^2.0.2
copied to clipboard
Examples #
Digital signature #
In this example, we use Ed25519.
import 'package:better_cryptography/better_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 algorithm.sign(
message,
keyPair: keyPair,
);
print('Signature: ${signature.bytes}');
print('Public key: ${signature.publicKey.bytes}');

// Verify signature
final isSignatureCorrect = await algorithm.verify(
message,
signature: signature,
);
print('Correct signature: $isSignatureCorrect');
}
copied to clipboard
Key agreement #
In this example, we use X25519.
import 'package:better_cryptography/better_cryptography.dart';

Future<void> main() async {
final algorithm = X25519();

// Alice chooses her key pair
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');
}
copied to clipboard
Authenticated encryption #
In this example, we encrypt a message with AesCtr
and append a Hmac
message authentication code.
import 'dart:convert';
import 'package:better_cryptography/better_cryptography.dart';

Future<void> main() async {
// Message we want to encrypt
final message = utf8.encode('Hello encryption!');

// Choose the cipher
final algorithm = AesCtr(macAlgorithm: Hmac.sha256()));

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

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

// Decrypt
final clearText = await algorithm.decrypt(
secretBox,
secretKey: secretKey,
);
print('Cleartext: ${utf8.decode(clearText)}');
}
copied to clipboard
Hashing #
In this example, we use Sha512.
import 'package:better_cryptography/better_cryptography.dart';

Future<void> main() async {
final sink = Sha512().newHashSink();

// 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}');
}
copied to clipboard