Merge pull request #163 from terrier989/master

Adds Argon2id implementation.

Author: terrier989

cryptography/CHANGELOG.md

@@ -1,3 +1,9 @@
+## 2.7.0
+* Adds a cross-platform of Argon2id, a highly recommended algorithm for password hashing.
+* Introduces a dependency on "package:ffi" (a package by Google). A memory allocator in the package
+  is used when the Argon2 implementation distributes computation to multiple isolates.
+* Small backwards-compatible changes in Blake2b and DartBlake2b API.
+
 ## 2.6.1
 * Fixes incorrect base class constraints.
 

cryptography/README.md

@@ -33,8 +33,8 @@ Android / iOS / Mac OS X operating system APIs whenever possible.
 In _pubspec.yaml_:
 ```yaml
 dependencies:
-  cryptography: ^2.6.1
-  cryptography_flutter: ^2.3.1 # Remove if you don't use Flutter
+  cryptography: ^2.7.0
+  cryptography_flutter: ^2.3.2 # Remove if you don't use Flutter
 ```
 
 You are ready to go!
@@ -163,14 +163,15 @@ implementations are available:
   curve25519 Diffie-Hellman)
     * Throughput of the pure Dart implementation is around 1000 key agreements per second (in VM).
 
-### Key derivation algorithms
+### Key derivation / password hashing algorithms
 
-The following implementations are available:
+The following [KdfAlgorithm](https://pub.dev/documentation/cryptography/latest/cryptography/KdfAlgorithm-class.html) implementations are available:
 
-* [Hchacha20](https://pub.dev/documentation/cryptography/latest/cryptography/Hchacha20-clas.html)
-* [Hkdf](https://pub.dev/documentation/cryptography/latest/cryptography/Hkdf-class.html) (HKDF)
-* [Pbkdf2](https://pub.dev/documentation/cryptography/latest/cryptography/Pbkdf2-class.html) (
-  PBKDF2)
+* [Hchacha20](https://pub.dev/documentation/cryptography/latest/cryptography/Hchacha20-class.html)
+* [Hkdf](https://pub.dev/documentation/cryptography/latest/cryptography/Hkdf-class.html)
+* [Pbkdf2](https://pub.dev/documentation/cryptography/latest/cryptography/Pbkdf2-class.html)
+* [Argon2id](https://pub.dev/documentation/cryptography/latest/cryptography/Argon2id-class.html)
+  * Argon2id is the recommended algorithm for password hashing.
 
 ## Message authentication codes
 
@@ -392,6 +393,29 @@ Future<void> main() async {
 }
 ```
 
+## Password hashing
+In this example, we use [Argon2id](https://pub.dev/documentation/cryptography/latest/cryptography/Argon2id-class.html):
+```dart
+import 'package:cryptography/cryptography.dart';
+
+Future<void> main() async {
+  final algorithm = Argon2id(
+    memory: 10*1000, // 10 MB
+    parallelism: 2, // Use maximum two CPU cores.
+    iterations: 1, // For more security, you should usually raise memory parameter, not iterations.
+    hashLength: 32, // Number of bytes in the returned hash
+  );
+  
+  final secretKey = await algorithm.deriveKeyFromPassword(
+    password: 'qwerty',
+    nonce: [1, 2, 3],
+  );
+  final secretKeyBytes = await secretKey.extractBytes();
+
+  print('Hash: ${secretKeyBytes}');
+}
+```
+
 ## Hashing
 In this example, we use [Sha256](https://pub.dev/documentation/cryptography/latest/cryptography/Sha256-class.html):
 ```dart

cryptography/lib/src/cryptography/algorithms.dart

@@ -440,23 +440,46 @@ abstract class AesGcm extends Cipher {
   }
 }
 
-/// _Argon2id_ ([draft-irtf-cfrg-argon2-03](https://tools.ietf.org/html/draft-irtf-cfrg-argon2-03))
-/// password hashing function.
+/// _Argon2id_ ([RFC 9106](https://datatracker.ietf.org/doc/rfc9106/))
+/// memory-hard password hashing function.
 ///
-/// _Argon2_ is known for winning _Password Hashing Competition_ 2015. The
-/// algorithm can provide much better security than older algorithms such as
-/// [Pbkdf2].
+/// _Argon2_ is known for winning _Password Hashing Competition_ 2015. OWASP
+/// [Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+/// describes it as first choice for password hashing.
 ///
-/// By default, [DartArgon2id], our pure Dart implementation, will be used.
+/// The default implementation is [DartArgon2id], our pure Dart implementation.
+///
+/// ## Things to know
+///   * You need to choose:
+///     * [memory]
+///       * Number of 1kB blocks of memory needed to compute the hash.
+///       * Higher is better for security. You should experiment what is good
+///         for your system. We recommend to start from 1000 (= 1 MB) and go
+///         as high as you can.
+///     * [parallelism]
+///       * Maximum number of parallel computations.
+///       * You should choose a small number such as 1 or 4.
+///     * [iterations]
+///       * Number of iterations. Higher is better for security, but usually
+///         you should use value `1` because it makes more sense (from security
+///         point of view) to raise [memory] parameter instead.
+///     * [hashLength]
+///       * The value should be at least 16 bytes. More than 32 bytes is
+///         unnecessary from security point of view.
+///   * OWASP [suggests](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html)
+///     the following parameter values:
+///       * memory = 19 MiB of memory
+///       * parallelism = 1
+///       * iterations = 2
 ///
 /// ## Example
 /// ```
 /// import 'package:cryptography/cryptography.dart';
 ///
 /// Future<void> main() async {
 ///   final algorithm = Argon2id(
-///     parallelism: 3,
-///     memorySize: 10000000,
+///     parallelism: 4,
+///     memory: 10000, // 10 000 x 1kB block = 10 MB
 ///     iterations: 3,
 ///     hashLength: 32,
 ///   );
@@ -479,13 +502,13 @@ abstract class AesGcm extends Cipher {
 abstract class Argon2id extends KdfAlgorithm {
   factory Argon2id({
     required int parallelism,
-    required int memorySize,
+    required int memory,
     required int iterations,
     required int hashLength,
   }) {
     return Cryptography.instance.argon2id(
       parallelism: parallelism,
-      memorySize: memorySize,
+      memory: memory,
       iterations: iterations,
       hashLength: hashLength,
     );
@@ -495,31 +518,30 @@ abstract class Argon2id extends KdfAlgorithm {
   const Argon2id.constructor();
 
   @override
-  int get hashCode => parallelism ^ memorySize ^ iterations ^ hashLength;
+  int get hashCode => parallelism ^ memory ^ iterations ^ hashLength;
 
   /// Hash length.
   int get hashLength;
 
   /// Number of iterations.
   int get iterations;
 
-  /// Minimum number of bytes attacker needs to store in memory for each
-  /// attempt.
-  int get memorySize;
+  /// Minimum number of 1 kB blocks needed to compute the hash.
+  int get memory;
 
   /// Maximum number of processors attacker can use concurrently for each
   /// attempt.
   int get parallelism;
 
   /// Argon2id algorithm version number.
   @nonVirtual
-  int get version => 0x13;
+  int get version => 19;
 
   @override
   bool operator ==(other) =>
       other is Argon2id &&
       parallelism == other.parallelism &&
-      memorySize == other.memorySize &&
+      memory == other.memory &&
       iterations == other.iterations &&
       hashLength == other.hashLength;
 
@@ -535,14 +557,14 @@ abstract class Argon2id extends KdfAlgorithm {
   Future<SecretKey> deriveKey({
     required SecretKey secretKey,
     required List<int> nonce,
-    List<int> k = const <int>[],
-    List<int> ad = const <int>[],
+    List<int> optionalSecret = const <int>[],
+    List<int> associatedData = const <int>[],
   });
 
   @override
-  String toString() => 'Argon2id(\n'
+  String toString() => '$runtimeType(\n'
       '  parallelism: $parallelism,\n'
-      '  memorySize: $memorySize,\n'
+      '  memory: $memory,\n'
       '  iterations: $iterations,\n'
       '  hashLength: $hashLength,\n'
       ')';
@@ -617,6 +639,19 @@ abstract class Blake2b extends HashAlgorithm implements MacAlgorithm {
   })  : assert(hashLengthInBytes > 0),
         assert(hashLengthInBytes <= defaultHashLengthInBytes);
 
+  /// Enables you to replace [hashLengthInBytes].
+  ///
+  /// Subclasses should replace this with their own implementation.
+  Blake2b replace({int? hashLength}) {
+    hashLength ??= hashLengthInBytes;
+    if (hashLength == hashLengthInBytes) {
+      return this;
+    }
+    return Blake2b(
+      hashLengthInBytes: hashLength,
+    );
+  }
+
   @override
   void checkParameters({
     int? length,

cryptography/lib/src/cryptography/cryptography.dart

@@ -108,8 +108,8 @@ abstract class Cryptography {
 
   /// A factory used by [Argon2id].
   Argon2id argon2id({
+    required int memory,
     required int parallelism,
-    required int memorySize,
     required int iterations,
     required int hashLength,
   });

cryptography/lib/src/cryptography/kdf_algorithm.dart

@@ -19,10 +19,10 @@ import 'package:cryptography/cryptography.dart';
 /// Abstract superclass for Key Derivation Algorithms (KDFs).
 ///
 /// ## Available algorithms
-///   * [Argon2id] (suitable for password hashing)
+///   * [Argon2id] (recommended for password hashing)
 ///   * [Hchacha20]
 ///   * [Hkdf]
-///   * [Pbkdf2] (suitable for password hashing)
+///   * [Pbkdf2]
 abstract class KdfAlgorithm {
   const KdfAlgorithm();