Update the documentation

docs/src/Implementers.rst

@@ -11,36 +11,22 @@ Guidelines
 ----------
 
 New implementations **MUST** be delivered as Composer packages.
-
-Such a package :
-*   **MUST** contain a requirement on ``fpoirotte/cryptal``
-    as part of the ``require`` section in their :file:`composer.json` file.
-
-*   **MUST** provide an implementation for one or several of the interfaces
-    defined in the ``\fpoirotte\Cryptal\Implementers`` namespace.
-
-*   **MUST** use ``cryptal-plugin`` as their installer ``type``.
-
-*   **MUST** declare a key named ``cryptal.entrypoint`` in the ``extra`` section
-    of their :file:`composer.json` file, pointing to a class implementing
-    the ``fpoirotte\Cryptal\Implementers\PluginInterface`` interface.
-
-To make it easier to find compatibles plugins for Cryptal
-on `Packagist <https://packagist.org/>`_, an implementation
-**MAY** ``provide`` the ``fpoirotte/cryptal-implementation`` virtual package
-in their :file:`composer.json`
-
-The version number associated with the provided virtual package **SHOULD**
-be set to a sensible value.
+Such a package **MUST** provide an implementation for one or several
+of the interfaces defined in the ``\fpoirotte\Cryptal\Implementers`` namespace.
 
 It is **RECOMMENDED** that implementers always support as many algorithms
 recognized by the Cryptography Abstraction Layer as the underlying library
 and Cryptal permit when adding support for a feature.
 
+The following sections describes how to turn a regular Composer package
+into a Cryptal plugin.
 
 Creating a new plugin
 ---------------------
 
+Update your :file:`composer.json` file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 The basic skeleton for a plugin's :file:`composer.json` looks like this:
 
 ..  sourcecode:: json
@@ -67,9 +53,43 @@ The basic skeleton for a plugin's :file:`composer.json` looks like this:
         }
     }
 
+
+There are four important things to note:
+
+*   The package's type **MUST** be set to ``cryptal-plugin`` in order for the
+    plugin to be properly recognized as such.
+
+*   The package **MUST** contain a requirement on ``fpoirotte/cryptal``
+    as part of the ``require`` section, so that the core files needed
+    to load and use the plugin are available at runtime.
+
+*   To make it easier to find compatible plugins for Cryptal
+    on `Packagist <https://packagist.org/>`_, an implementation
+    **SHOULD** ``provide`` the ``fpoirotte/cryptal-implementation``
+    virtual package in its :file:`composer.json` file.
+
+    The version number associated with the provided virtual package **SHOULD**
+    be set to a sensible value.
+
+*   The package **MUST** declare a key named ``cryptal.entrypoint``
+    in the ``extra`` section of their :file:`composer.json` file,
+    pointing to a class that implements the
+    ``fpoirotte\Cryptal\Implementers\PluginInterface`` interface.
+
+    If your plugin provides implementations for several features
+    and you would like each feature to use its own entry point,
+    you may also use an array of entry points here in place
+    of a string.
+
+Write the code for the entry point
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The entry point is responsible for registering any algorithm implemented
+by the plugin into Cryptal's registry.
+
 Assuming the plugin adds support for the AES cipher using 128 bit keys (AES-128)
 in Electronic Codebook (ECB) mode, the MD5 hash algorithm and the HMAC message
-authentication code, the entry point will look like this:
+authentication code, an entry point may look like this:
 
 ..  sourcecode:: inline-php
 
@@ -109,6 +129,25 @@ authentication code, the entry point will look like this:
             );
     }
 
+The ``RegistryWrapper`` provides 3 methods, meant to declare support for
+new ciphers (addCipher), hash algorithms (addHash) and message authentication
+codes (addMac).
+
+Each of these methods expects the full path to a class providing the algorithm
+as their first argument, followed by Cryptal's identifier for that algorithm
+and an identifier for the implementation type.
+
+For ciphers, the algorithm identifier is made of two arguments:
+
+*   The cipher's identifier itself
+    (one of the values declared in the ``CipherEnum`` enumeration)
+
+*   The mode of operations which can be applied to this cipher
+    (one of the values declared in the ``ModeEnum`` enumeration)
+
+For hash and MAC algorithms, just pass the algorithm's identifier defined
+in ``HashEnum`` or ``MacEnum``, respectively.
+
 The implementation type **SHOULD** match the actual nature of the algorithm's
 implementation:
 
@@ -121,6 +160,9 @@ implementation:
 *   ``TYPE_USERLAND()`` **SHOULD** be used for algorithms implemented using
     regular (userland) PHP code, as opposed to code from a PHP extension.
 
+Cryptal uses this information at runtime to determine the fastest/most secure
+implementation it can use.
+
 Available plugins
 -----------------
 

docs/src/Installation.rst

@@ -17,11 +17,17 @@ Cryptal supports 3 types of implementations:
 *   PHP code, which is slower and less secure, but provides support for niche
     algorithms.
 
+Choosing the plugin(s) to install
+---------------------------------
+
 The following tables list the algorithms provided by each plugin, with their
 implementation type. "Core" means the algorithm is provided by the Cryptal
 package itself and does not require any additional plugin to work.
 
-..  list-table:: Cipher algorithms
+Cipher algorithms
+~~~~~~~~~~~~~~~~~
+
+..  list-table::
     :header-rows: 1
     :stub-columns: 1
 
@@ -68,21 +74,21 @@ package itself and does not require any additional plugin to work.
         -   n/a
 
     *   -   Camellia-128
-        -   n/a
+        -   PHP code
         -   n/a
         -   compiled
         -   n/a
         -   n/a
 
     *   -   Camellia-192
-        -   n/a
+        -   PHP code
         -   n/a
         -   compiled
         -   n/a
         -   n/a
 
     *   -   Camellia-256
-        -   n/a
+        -   PHP code
         -   n/a
         -   compiled
         -   n/a
@@ -107,7 +113,7 @@ package itself and does not require any additional plugin to work.
         -   n/a
         -   n/a
         -   n/a
-        -   ?
+        -   n/a
 
     *   -   DES
         -   n/a
@@ -144,7 +150,10 @@ package itself and does not require any additional plugin to work.
         -   compiled
         -   n/a
 
-..  list-table:: Hash algorithms
+Hashing algorithms
+~~~~~~~~~~~~~~~~~~
+
+..  list-table::
     :header-rows: 1
     :stub-columns: 1
 
@@ -225,7 +234,10 @@ package itself and does not require any additional plugin to work.
         -   compiled
         -   compiled
 
-..  list-table:: MAC algorithms
+Message authentication algorithms
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+..  list-table::
     :header-rows: 1
     :stub-columns: 1
 
@@ -277,8 +289,13 @@ package itself and does not require any additional plugin to work.
         -   n/a
         -   n/a
 
-Once you have decided which algorithms you are going to use, simply install
-a plugin that provides this algorithm using the selected implementation type:
+
+Installing the plugins
+----------------------
+
+Once you have determined the algorithms you are going to use and the plugins
+providing these algorithms that you want to use, execute the following commands
+to install the appropriate plugins:
 
 ..  sourcecode:: bash
 
@@ -298,4 +315,3 @@ a plugin that provides this algorithm using the selected implementation type:
     $ php composer.php require fpoirotte/cryptal-hash
 
 .. vim: ts=4 et
-