Merge pull request bcgit#209 from hoylen/documentation

Tutorial articles
samu-d · Dec 12, 2019 · d78b632 · d78b632
2 parents c5eb596 + 526dda0
commit d78b632
Show file tree

Hide file tree

Showing 22 changed files with 4,289 additions and 41 deletions.
diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@ and development of this library.
 Pointy Castle
 =============
 
-A Dart library for encryption and decryption. As of today, most of the classes
+A Dart library for encryption and decryption. In this release, most of the classes
 are ports of Bouncy Castle from Java to Dart. The porting is almost always
 direct except for some classes that had been added to ease the use of low level
 data.
@@ -21,9 +21,9 @@ To make sure nothing fails, tests and benchmarks for every algorithm are
 provided. The expected results are taken from the Bouncy Castle Java version
 and also from standards, and matched against the results got from Pointy Castle.
 
-# Algorithms
+## Algorithms
 
-As of the last release, the following algorithms are implemented:
+In this release, the following algorithms are implemented:
 
 **Block ciphers:**
   * AES
@@ -87,65 +87,177 @@ As of the last release, the following algorithms are implemented:
   * Based on block cipher in CTR mode with auto reseed (for forward security)
   * Based on Fortuna algorithm
 
+### Instantiating implementation objects
 
-# Usage
+There are two ways to instantiate objects that implement the
+algorithms:
 
-There are two ways to use the algorithms that PointyCastle provides: with or
-without using the registry.
+- using the registry, or
+- without the registry.
 
-## Registry
+#### Using the registry
 
-The registry allows users to easily instantiate classes for the algorithms using
-the algorithm shorthands like given in the list above.  It also makes it possible
-to seamlessly chain different algorithms together.  For example:
+Using the registry, the algorithm name is provided to high-level class
+factories.
+
+This is especially convenient when an algorithm involves multiple
+algorithm implementation classes to implement. All the necessary
+classes can all be instantiated with a single name
+(e.g. "HMAC/SHA-256" or "SHA-1/HMAC/PBKDF2"), and they are
+automatically combined together with the correct values.
+
+For example,
 
 ```dart
-import "package:pointycastle/pointycastle.dart";
+final sha256 = Digest("SHA-256");
+final sha1 = Digest("SHA-1");
+final md5 = Digest("MD5");
+
+final hmacSha256 = Mac("SHA-256/HMAC");
+final hmacSha1 = Mac("SHA-1/HMAC");
+final hmacMd5 = Mac("MD5/HMAC");
 
-void main() {
-  Digest sha256 = new Digest("SHA-256");
-  // or
-  KeyDerivator derivator = new KeyDerivator("SHA-1/HMAC/PBKDF2");
-}
+final derivator = KeyDerivator("SHA-1/HMAC/PBKDF2");
+
+final signer = Signer("SHA-256/RSA");
 ```
 
-## Without the registry
+#### Without the registry
+
+Without the registry, each implementation class must be instantiated
+using its constructor.
+
+If an algorithm involves multiple algorithm implementation classes,
+they each have to be individually instantiated and combined together
+with the correct values.
+
+For example,
+
+``` dart
+final sha256 = SHA256Digest();
+final sha1 = SHA1Digest();
+final md5 = MD5Digest();
+
+final hmacSha256 = HMac(SHA256Digest(), 64);
+final hmacSha512 = HMac(SHA512Digest(), 128);
+final hmacMd5 = HMac(MD5Digest(), 64);
+
+final derivator = PBKDF2KeyDerivator(HMac(SHA256Digest(), 64));
+
+final signer = RSASigner(SHA256Digest(), '0609608648016503040201');
+```
+
+#### Registry vs without registry
 
 Using the registry means that all algorithms will be imported by default, which
 can possibly increase the compiled size of your program.  To avoid this, it is
 possible to import algorithms one by one.  In that case, you can decide to either
 use the classes directly, or still use the registry.  But remember that the
-registry only contains the classes that you import.  For example:
+registry only contains the classes that you import.
 
-```dart
-import "package:pointycastle/api.dart";
+### Importing libraries
 
-import "package:pointycastle/digests/sha256.dart";
+A program can take one of these three approaches for importing Point
+Castle libraries:
+
+- only import pointycastle.dart;
+- only import exports.dart; or
+- import api.dart and individual libraries as needed.
+
+#### Only import pointycastle.dart
 
-import "package:pointycastle/digests/sha1.dart";
-import "package:pointycastle/macs/hmac.dart";
-import "package:pointycastle/key_derivators/pbkdf2.dart";
+The "pointycastle.dart" file exports:
 
-void main() {
-  Digest sha256 = new SHA256Digest();
-  // or
-  KeyDerivator derivator = new PBKDF2KeyDerivator(
-      new HMac(new SHA1Digest(), 64));
+- the high-level API; and
+- implementations of the interfaces.
 
-  // But the registry keeps working for all imported algorithms:
+But it does not export any of the algorithm implementation classes.
 
-  Digest sha256 = new Digest("SHA-256");
-  // or
-  KeyDerivator derivator = new KeyDerivator("SHA-1/HMAC/PBKDF2");
-}
+``` dart
+import "package:pointycastle/pointycastle.dart";
+```
+
+With this import, **none** of the implementation classes can be
+instantiated directly.  The program can only use the registry.
+
+For example,
+
+``` dart
+final sha256 = Digest("SHA-256");
+// final md5 = MD5Digest(); // not available
+final p = Padding("PKCS7");
+// final s = FortunaRandom(); // not available
 ```
 
+#### Only import exports.dart
+
+The "export.dart" file exports:
+
+- the high-level API,
+- implementations of the interfaces; and
+- every algorithm implementation class.
+
+That is, everything!
+
+``` dart
+import "package:pointycastle/export.dart";
+```
+
+With this import, **all** of the implementation classes can be
+instantiated directly.  The program can also use the registry.
+
+
+For example, this works without any additional imports:
+
+``` dart
+final sha256 = Digest("SHA-256");
+final md5 = MD5Digest();
+final p = Padding("PKCS7");
+final s = FortunaRandom();
+```
+
+#### Import api.dart and individual libraries
+
+The "api.dart" exports only:
+
+- the high-level API.
+
+It does not include the implementations of the interfaces, nor any
+algorithm implementation class.
+
+``` dart
+import "package:pointycastle/api.dart";
+// additional imports will be needed
+```
+
+With this import, only **some** of the implementation classes can be
+instantiated directly (i.e. those that are also explicitly imported).
+The program can also use the registry.
+
+For example, the following only works because of the additional imports:
+
+``` dart
+// In addition to "package:pointycastle/api.dart":
+import "package:pointycastle/digests/sha256.dart";
+import "package:pointycastle/digests/md5.dart"
+import 'package:pointycastle/paddings/pkcs7.dart';
+
+final sha256 = Digest("SHA-256");
+final md5 = MD5Digest();
+final p = Padding("PKCS7");
+// final s = FortunaRandom(); // not available without 'package:pointycastle/random/fortuna_random.dart'
+```
+
+## Tutorials
+
+Some articles on how to use some of Pointy Castle's features can be
+found under the _tutorials_ directory in the sources.
 
-## Libraries
+- [Calculating a digest](https://github.com/PointyCastle/pointycastle/blob/master/tutorials/digest.md) - calculating a hash or digest (e.g. SHA-256, SHA-1, MD5)
+- [Calculating a HMAC](https://github.com/PointyCastle/pointycastle/blob/master/tutorials/hmac.md) - calculating a hash-based message authentication code (e.g. HMAC-SHA256, HMAC-SHA1)
+- [Using AES-CBC](https://github.com/PointyCastle/pointycastle/blob/master/tutorials/aes-cbc.md) - block encryption and decryption with AES-CBC
+- [Using RSA](https://github.com/PointyCastle/pointycastle/blob/master/tutorials/rsa.md) - key generation, signing/verifying, and encryption/decryption
+- Some [tips](https://github.com/PointyCastle/pointycastle/blob/master/tutorials/tips.md) on using Pointy Castle
 
- * `package:pointycastle/pointycastle.dart`: exports the high-level API and the
-    registry loaded with all available implementations
- * `package:pointycastle/api.dart`: exports the high-level API and the registry
-    without any implementations
- * `package:pointycastle/export.dart`: exports the API and all implementation
-    classes
+_Note: the above links are to the most recent versions on the master
+branch on GitHub. They may be different from the version here._