Merge branch 'tutorial-updates' of https://github.com/hoylen/pc-dart …

…into hoylen-tutorial-updates

.github/workflows/chrome.workflow.yml

@@ -33,4 +33,4 @@ jobs:
         run: dart pub get
 
       - name: Test chrome
-        run: pub run test -p chrome
+        run: dart pub run test -p chrome

.github/workflows/node.workflow.yml

@@ -33,4 +33,4 @@ jobs:
         run: dart pub get
 
       - name: Test node
-        run: pub run test -p node
+        run: dart pub run test -p node

.github/workflows/vm.workflow.yml

@@ -33,4 +33,4 @@ jobs:
         run: dart pub get
 
       - name: Test dartvm
-        run: pub run test -p vm
+        run: dart pub run test -p vm

.gitlab-ci.yml

@@ -10,24 +10,27 @@ test-code-vm:
   stage: test
   script:
     - "export PATH=$PATH:/usr/lib/dart/bin:$HOME/.pub-cache/bin; \
-    pub get; pub run test;"
+    dart pub get; \
+    dart pub run test;"
 
 test-code-node:
   stage: test
   script:
     - "export PATH=$PATH:/usr/lib/dart/bin:$HOME/.pub-cache/bin; \
-    pub get; pub run test --timeout 15m -p node"
+    dart pub get; \
+    dart pub run test --timeout 15m -p node"
 
 test-code-chrome:
   stage: test
   script:
     - "export PATH=$PATH:/usr/lib/dart/bin:$HOME/.pub-cache/bin; \
-    pub get; pub run test --timeout 15m -p chrome"
+    dart pub get; \
+    dart pub run test --timeout 15m -p chrome"
 
 score-pana:
   stage: score
   script:
     - "export PATH=$PATH:/usr/lib/dart/bin:$HOME/.pub-cache/bin; \
-    pub get; \
-    pub global activate pana; \
+    dart pub get; \
+    dart pub global activate pana; \
     pana ."

.travis.yml

@@ -2,6 +2,6 @@ language: dart
 dart:
   - stable
 script:
-  - pub run test
-  - pub global activate pana
-  - pana .
+  - dart pub run test
+  - dart pub global activate pana
+  - dart pana .

tutorials/aes-cbc.md

@@ -42,10 +42,15 @@ import 'dart:typed_data';
 
 import "package:pointycastle/export.dart";
 
-Uint8List aesCbcEncrypt(Uint8List key, Uint8List iv, Uint8List paddedPlaintext) {
+Uint8List aesCbcEncrypt(
+    Uint8List key, Uint8List iv, Uint8List paddedPlaintext) {
+  assert([128, 192, 256].contains(key.length * 8));
+  assert(128 == iv.length * 8);
+  assert(128 == paddedPlaintext.length * 8);
+
   // Create a CBC block cipher with AES, and initialize with key and IV
 
-  final cbc = CBCBlockCipher(AESFastEngine())
+  final cbc = CBCBlockCipher(AESEngine())
     ..init(true, ParametersWithIV(KeyParameter(key), iv)); // true=encrypt
 
   // Encrypt the plaintext block-by-block
@@ -62,9 +67,13 @@ Uint8List aesCbcEncrypt(Uint8List key, Uint8List iv, Uint8List paddedPlaintext)
 }
 
 Uint8List aesCbcDecrypt(Uint8List key, Uint8List iv, Uint8List cipherText) {
+  assert([128, 192, 256].contains(key.length * 8));
+  assert(128 == iv.length * 8);
+  assert(128 == cipherText.length * 8);
+
   // Create a CBC block cipher with AES, and initialize with key and IV
 
-  final cbc = CBCBlockCipher(AESFastEngine())
+  final cbc = CBCBlockCipher(AESEngine())
     ..init(false, ParametersWithIV(KeyParameter(key), iv)); // false=decrypt
 
   // Decrypt the cipherText block-by-block
@@ -85,12 +94,13 @@ The _key_ must be exactly 128-bits, 192-bits or 256-bits (i.e. 16, 24
 or 32 bytes). This is what determines whether AES-128, AES-192 or
 AES-256 is being performed.
 
-The _iv_ must be exactly 128-bites (16 bytes) long, which is the AES
+The _iv_ must be exactly 128-bits (16 bytes) long, which is the AES
 block size.
 
 The _paddedPlainText_ must be a multiple of the block size
 (128-bits). If the data being encrypted is not the correct length, it
-must be padded before it can be processed by AES.
+must be padded before it can be processed by AES. The implementations
+of padding algorithms in Pointy Castle can be used for this.
 
 
 ## Details
@@ -112,7 +122,7 @@ If the registry is not used, invoke the block cipher's constructor,
 passing in the AES implementation as a parameter.
 
 ```dart
-final aesCbc = CBCBlockCipher(AESFastEngine());
+final aesCbc = CBCBlockCipher(AESEngine());
 ```
 
 ### Initialize with key and IV

tutorials/digest.md

@@ -31,17 +31,19 @@ import 'dart:typed_data';
 import "package:pointycastle/export.dart";
 
 Uint8List sha256Digest(Uint8List dataToDigest) {
-
-  final d = new SHA256Digest();
+  final d = SHA256Digest();
 
   return d.process(dataToDigest);
 }
 
 void main(List<String> args) {
-  for (final data in args) {
+  final valuesToDigest = (args.isNotEmpty) ? args : ['Hello world!'];
+
+  for (final data in valuesToDigest) {
     print('Data: "$data"');
-    final hashValue = sha256Digest(utf8.encode(data));
-	print('SHA-256: $hashValue');
+    final hash = sha256Digest(utf8.encode(data) as Uint8List);
+    print('SHA-256: $hash');
+    print('SHA-256: ${bin2hex(hash)}'); // output in hexadecimal
   }
 }
 ```
@@ -59,7 +61,7 @@ If using the registry, invoke the `Digest` factory with the name of
 the digest algorithm.
 
 ```dart
-final d = new Digest("SHA-256");
+final d = Digest("SHA-256");
 ```
 
 Possible names include: "MD2", "MD4", "MD5", "RIPEMD-128",
@@ -81,7 +83,7 @@ If the registery is not used, invoke the digest implementation's
 constructor.
 
 ```dart
-final d = new SHA256Digest(); // SHA-256
+final d = SHA256Digest(); // SHA-256
 ```
 
 All of the available digest classes of are listed as the implementers
@@ -153,7 +155,7 @@ required if previously provided data is abandoned.
 final part1 = utf8.encode('Hello ');
 final part2 = utf8.encode('world!');
 
-final d = new SHA256Digest();
+final d = SHA256Digest();
 final hash = Uint8List(d.digestSize);
 
 // Without rest

tutorials/examples/README.md

@@ -7,4 +7,25 @@ used in the tutorials.
 They are not officially a part of the tutorials, and are only provided
 on an as-is basis.
 
-All of them accept the "-h" or "--help" option.
+## Running the examples
+
+Run "dart pub get" in the parent directory, and then run the example Dart
+Dart programs. For example:
+
+```sh
+dart aes-cbc-direct.dart
+dart digest-direct.dart "foobar"
+dart rsa-demo.dart
+```
+
+All of these example programs accept the "-h" or "--help" option.
+
+## Checking the text in the tutorials
+
+Fragments of the Dart code are copied into the MarkDown tutorial files
+in the parent directory.
+
+The fragments between comment lines containing "BEGIN EXAMPLE" and
+"END EXAMPLE" should appear literally the same in the MarkDown file.
+Other fragments have been modified to make them more readable in the
+tutorial and more functional in the example code.

tutorials/examples/aes-cbc-direct.dart

@@ -10,22 +10,16 @@ import 'package:pointycastle/export.dart';
 import 'package:pointycastle/src/platform_check/platform_check.dart';
 
 // Code convention: variable names starting with underscores are examples only,
-// and should be implementated according to the needs of the program.
+// and should be implemented according to the needs of the program.
 
 //----------------------------------------------------------------
+// BEGIN EXAMPLE in "../aes-cbc.md"
 
 Uint8List aesCbcEncrypt(
     Uint8List key, Uint8List iv, Uint8List paddedPlaintext) {
-  if (![128, 192, 256].contains(key.length * 8)) {
-    throw ArgumentError.value(key, 'key', 'invalid key length for AES');
-  }
-  if (iv.length * 8 != 128) {
-    throw ArgumentError.value(iv, 'iv', 'invalid IV length for AES');
-  }
-  if (paddedPlaintext.length * 8 % 128 != 0) {
-    throw ArgumentError.value(
-        paddedPlaintext, 'paddedPlaintext', 'invalid length for AES');
-  }
+  assert([128, 192, 256].contains(key.length * 8));
+  assert(128 == iv.length * 8);
+  assert(128 == paddedPlaintext.length * 8);
 
   // Create a CBC block cipher with AES, and initialize with key and IV
 
@@ -44,19 +38,11 @@ Uint8List aesCbcEncrypt(
 
   return cipherText;
 }
-//----------------------------------------------------------------
 
 Uint8List aesCbcDecrypt(Uint8List key, Uint8List iv, Uint8List cipherText) {
-  if (![128, 192, 256].contains(key.length * 8)) {
-    throw ArgumentError.value(key, 'key', 'invalid key length for AES');
-  }
-  if (iv.length * 8 != 128) {
-    throw ArgumentError.value(iv, 'iv', 'invalid IV length for AES');
-  }
-  if (cipherText.length * 8 % 128 != 0) {
-    throw ArgumentError.value(
-        cipherText, 'cipherText', 'invalid length for AES');
-  }
+  assert([128, 192, 256].contains(key.length * 8));
+  assert(128 == iv.length * 8);
+  assert(128 == cipherText.length * 8);
 
   // Create a CBC block cipher with AES, and initialize with key and IV
 
@@ -76,6 +62,8 @@ Uint8List aesCbcDecrypt(Uint8List key, Uint8List iv, Uint8List cipherText) {
   return paddedPlainText;
 }
 
+// END EXAMPLE
+
 //================================================================
 // Supporting functions
 //

tutorials/examples/aes-cbc-registry.dart

@@ -10,7 +10,7 @@ import 'package:pointycastle/pointycastle.dart';
 import 'package:pointycastle/src/platform_check/platform_check.dart';
 
 // Code convention: variable names starting with underscores are examples only,
-// and should be implementated according to the needs of the program.
+// and should be implemented according to the needs of the program.
 
 //----------------------------------------------------------------
 
@@ -44,6 +44,7 @@ Uint8List aesCbcEncrypt(
 
   return cipherText;
 }
+
 //----------------------------------------------------------------
 
 Uint8List aesCbcDecrypt(Uint8List key, Uint8List iv, Uint8List cipherText) {

tutorials/examples/digest-direct.dart

@@ -19,12 +19,16 @@ import 'dart:typed_data';
 
 import 'package:pointycastle/export.dart';
 
+// BEGIN EXAMPLE in "../digest.md"
+
 Uint8List sha256Digest(Uint8List dataToDigest) {
   final d = SHA256Digest();
 
   return d.process(dataToDigest);
 }
 
+// END EXAMPLE
+
 void main(List<String> args) {
   if (args.contains('-h') || args.contains('--help')) {
     print('Usage: digest-direct {stringsToDigest}');
@@ -35,7 +39,7 @@ void main(List<String> args) {
 
   for (final data in valuesToDigest) {
     print('Data: "$data"');
-    final hash = sha256Digest(Uint8List.fromList(utf8.encode(data)));
+    final hash = sha256Digest(utf8.encode(data) as Uint8List);
     print('SHA-256: $hash');
     print('SHA-256: ${bin2hex(hash)}'); // output in hexadecimal
   }

tutorials/examples/hmac-direct.dart

@@ -13,14 +13,17 @@ import 'dart:typed_data';
 
 import 'package:pointycastle/export.dart';
 
-Uint8List hmacSha1(Uint8List hmacKey, Uint8List data) {
-  final hmac =
-      HMac(SHA256Digest(), 64) // HMAC SHA-256 must use block length of 64
-        ..init(KeyParameter(hmacKey));
+// BEGIN EXAMPLE in "../hmac.md"
+
+Uint8List hmacSha256(Uint8List hmacKey, Uint8List data) {
+  final hmac = HMac(SHA256Digest(), 64) // HMAC SHA-256: block must be 64 bytes
+    ..init(KeyParameter(hmacKey));
 
   return hmac.process(data);
 }
 
+// END EXAMPLE
+
 void hmacWithOtherDigestAlgorithms(Uint8List hmacKey, Uint8List data) {
   final hmacSha256 = HMac(SHA256Digest(), 64);
   final hmacSha512 = HMac(SHA512Digest(), 128);
@@ -45,7 +48,8 @@ void main(List<String> args) {
   final data = utf8.encode(args[1]); // second argument is the data
 
   print('Data: "${args[1]}"');
-  final hmacValue = hmacSha1(Uint8List.fromList(key), Uint8List.fromList(data));
+  final hmacValue =
+      hmacSha256(Uint8List.fromList(key), Uint8List.fromList(data));
   //print('HMAC SHA-1: $hmacValue');
   print('HMAC SHA-1: ${bin2hex(hmacValue)}');
 

tutorials/examples/rsa-demo.dart

@@ -8,7 +8,6 @@
 /// Invoke with "-l" to use longer plaintext.
 
 import 'dart:convert';
-import 'dart:math';
 import 'dart:typed_data';
 
 // For using the registry:
@@ -53,7 +52,7 @@ AsymmetricKeyPair<RSAPublicKey, RSAPrivateKey> generateRSAkeyPair(
 
   final pair = keyGen.generateKeyPair();
 
-  // Examine the generated key-pair
+  // Cast the generated key pair into the RSA key types
 
   final myPublic = pair.publicKey as RSAPublicKey;
   final myPrivate = pair.privateKey as RSAPrivateKey;
@@ -87,6 +86,7 @@ Uint8List rsaSign(RSAPrivateKey privateKey, Uint8List dataToSign) {
   // corresponding to the digest algorithm, otherwise the signature won't
   // verify.
 
+  // initialize with true, which means sign
   signer.init(true, PrivateKeyParameter<RSAPrivateKey>(privateKey));
 
   final sig = signer.generateSignature(dataToSign);
@@ -99,14 +99,15 @@ Uint8List rsaSign(RSAPrivateKey privateKey, Uint8List dataToSign) {
 
 bool rsaVerify(
     RSAPublicKey publicKey, Uint8List signedData, Uint8List signature) {
-  final sig = RSASignature(signature);
   //final signer = Signer('SHA-256/RSA'); // Get using registry
+  final sig = RSASignature(signature);
   final verifier = RSASigner(SHA256Digest(), '0609608648016503040201');
   // See _DIGEST_IDENTIFIER_HEXES in RSASigner for correct hex values to use
   // IMPORTANT: the correct digest identifier hex value must be used,
   // corresponding to the digest algorithm, otherwise the signature won't
   // verify.
 
+  // initialize with false, which means verify
   verifier.init(false, PublicKeyParameter<RSAPublicKey>(publicKey));
 
   return verifier.verifySignature(signedData, sig);