Add more documentation

doc/ASN1.rst

@@ -24,8 +24,8 @@ For the Ristretto255 group, typical message sizes are:
 * ``ImgGroupValue``: 34 Bytes.
 * ``SystemParameters``: 18 Bytes.
 * ``PrivateKey``: (up to) 36 Bytes.
-* ``PublicKey``: :math:`72 + |name|$` Bytes.
-* ``SharedSecret``: (up to) :math:`44 + 34t + 106n + |names|` Bytes.
+* ``PublicKey``: 72 + \|name\| Bytes.
+* ``SharedSecret``: (up to) 44 + 34t + 106n + \|names\| Bytes.
 * ``ReencryptedShare``: (up to) 279 Bytes.
 
 For the ``qr_mod_p`` group, the size depends on the safe prime. With a 4096 bit
@@ -192,3 +192,68 @@ ASN.1 module
     }
 
     END
+
+
+Examples for Qr
+---------------
+
+.. _asn1.examples.systemparameters.qr:
+
+::
+
+    SystemParameters for Qr, p=3395894518307:
+    30 16
+       06 0c  2b 06 01 04 01 83 ae 00 01 00 01 00
+       02 06  03 16 ab 16 22 23
+   
+  
+.. _asn1.examples.privatekey.qr:
+
+::
+
+    PrivateKey (Qr):
+    30 08
+       02 06  01 73 bf 82 ee c5
+
+.. _asn1.examples.publickey.qr:
+
+::
+
+    PublicKey (Qr):
+    30 1f
+       0c 0e  4a c3 b6 72 6e 20 48 65 69 73 73 6c 65 72
+       02 06  00 c6 f6 e4 2a e5
+       02 05  52 ba c7 b3 5d
+
+
+Examples for Ristretto255
+-------------------------
+.. _asn1.examples.systemparameters.rst255:
+
+::
+
+    SystemParameters for Rst255, always the same:
+    30 10
+       06 0c  2b 06 01 04 01 83 ae 00 01 00 01 01
+       05 00
+
+.. _asn1.examples.privatekey.rst255:
+
+::
+
+    PrivateKey (rst255):
+    30 21
+       02 1f  75 84 4f 25 73 27 05 32 4d ac fe 1f ed f8 5f a9
+              88 d0 9b 32 ab 32 e4 72 3e d4 f1 18 f0 3d 9a
+
+.. _asn1.examples.publickey.rst255:
+
+::
+
+    PublicKey (rst255):
+    30 54
+       0c 0e  4a c3 b6 72 6e 20 48 65 69 73 73 6c 65 72
+       04 20  ba 50 ea 13 2a a6 ae cc d1 24 55 20 b0 12 82 66
+              da ab 14 94 06 b8 62 f1 fc a7 2d 3f 0c 21 6f 31
+       04 20  6e a8 f7 6b 11 85 65 8a 36 a2 49 26 34 75 5d 1d
+              1b 8a 38 b2 7d 8f 42 80 be 2e 0a 97 4e 53 22 17

doc/changelog.rst

@@ -0,0 +1,14 @@
+Changelog
+=========
+
+0.3.0 - xxxx-xx-xx
+------------------
+.. note:: This version is not yet released and is under active development.
+
+* Improve documentation.
+
+
+0.2.0 - 2020-02-16
+------------------
+
+* First noteworthy release.

doc/index.rst

@@ -38,13 +38,14 @@ the encrypted share is public and it can be verified that the users followed the
 
    install
    usecases
-   workflow
+   workflow/index
    cli
    api
    math/index
    ASN1
    security
    glossary
+   changelog
 
 
 Indices and tables

doc/install.rst

@@ -25,3 +25,5 @@ And optionally:
 .. code-block:: console
 
     $ pip install gmpy2
+
+Source code is available on `GitHub <https://github.com/joernheissler/pvss>`_.

doc/workflow/index.rst

@@ -0,0 +1,15 @@
+Protocol Workflow
+=================
+The PVSS protocol consists of multiple steps. Each step yields one or multiple messsages that
+need to be available to the next steps.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   initialization
+   user-keypair
+   secret-splitting
+   receiver-keypair
+   reencryption
+   reconstruction

doc/workflow/initialization.rst

@@ -0,0 +1,52 @@
+Initialization
+==============
+Mathematical parameters must be chosen, such as a `cyclic group
+<https://en.wikipedia.org/wiki/Cyclic_group>`_ and several generators for it.
+
+In this implementation, the generators are determined deterministically by using a hash
+function. This eliminates the need to communicate the generators. It is vital that nobody has
+knowledge of the discrete logarith of any generator with regards to any other.  Hopefully the
+below strategies meet the `Rigidity <https://safecurves.cr.yp.to/rigid.html>`_ property.
+
+Ristretto255 group
+------------------
+The `Ristretto255 <https://ristretto.group/>`_ group is built upon `curve25519
+<https://cr.yp.to/ecdh.html>`_.  Basically this eliminates the cofactor from curve25519,
+ensuring that all group elements are unique and generate the complete group. The group and its
+operations are designed to be used for zero-knowledge protocols such as PVSS.
+
+`Libsodium <https://download.libsodium.org/doc/advanced/point-arithmetic/ristretto>`_ is used to
+carry out the various mathematical operations.
+
+Generators are determined by computing HMAC-SHA2-512 over the DER encoding of the :ref:`system
+parameters <asn1.examples.systemparameters.rst255>` and the LaTeX notation of the generator name
+is used as the hmac key, i.e. ``"G_0", "G_1", "g_0", "g_1"``.  The mac is passed through the
+``point_from_hash`` function to determine the generator points.
+
+The generators are:
+
+* :math:`G_0`: ``3cc42cdf5ffc59a96093c572e6429ce8c621695d8f99156819701070c9895b02``
+* :math:`G_1`: ``76e9d24f586f4878f24d11069e1ab0420f20793f73d79d2a7b753c522ce8c468``
+* :math:`g_0`: ``90199c1a0446a5bb8fb88de3266e27b74565b14c74de153f8054302434040a7b``
+* :math:`g_1`: ``0cd425c734d93957091c5871eb2c1f8dd222c56310c4df58117bce9bf212d820``
+
+
+Quadratic Residue Group
+-----------------------
+The `Multiplicative group <https://en.wikipedia.org/wiki/Multiplicative_group>`_ of `quadratic
+residues <https://en.wikipedia.org/wiki/Quadratic_residue>`_ modulo `safe prime
+<https://en.wikipedia.org/wiki/Safe_prime>`_ :math:`p = 2q+1` is commonly used for cryptographic
+operations, e.g. Diffie Hellmann. Useful property of quadratic residues are that they always
+generate the complete group, are easy to find (square any number) and it's easy to determine if
+a given number is a quadratic residue with the `Legendre symbol
+<https://en.wikipedia.org/wiki/Legendre_symbol>`_.  The implementation uses `gmpy2
+<https://pypi.org/project/gmpy2/>`_ to provide faster operations. Still, this group is very slow
+when compared to Ristretto255 and the message sizes are a lot bigger.
+
+To determine generators, HMAC-SHA2-256 is repeatedly computed and the results concatenated until
+at least twice the bit size of the prime :math:`p` is reached.  The LaTeX notation of the
+generator name is used as the key for the MAC operation. The input to the MAC is the previous
+MAC. As initial value, the DER representation of the :ref:`system parameters
+<asn1.examples.systemparameters.qr>` is used. Finally, the concatenated MACs are interpreted as
+an integer and squared to get a quadratic residue, i.e.  a generator for the group. The system
+parameters depend on the prime :math:`p`, so there will be different generators for each prime. 

doc/workflow/receiver-keypair.rst

@@ -0,0 +1,4 @@
+Recipient key pair generation
+=============================
+As soon as there is need to reassemble the secret, the intended recipient of the secret
+generates another keypair and shares the public key.

doc/workflow/reconstruction.rst

@@ -0,0 +1,3 @@
+Secret reconstruction
+=====================
+The recipient decrypts those shares and reassembles the secret.

doc/workflow/reencryption.rst

@@ -0,0 +1,3 @@
+Share re-encryption
+===================
+Some of the users decrypt their share and re-encrypt it with the recipient's public key.

doc/workflow/secret-splitting.rst

@@ -0,0 +1,5 @@
+Secret splitting
+================
+The *dealer* randomly generates a secret, computes a share for each user and encrypts each share
+with the corresponding user's public key.  The generated secret is used to encrypt the actual
+payload. The encrypted payload and the encrypted shares are published.

doc/workflow/user-keypair.rst

@@ -0,0 +1,4 @@
+User key pair generation
+========================
+Each user generates a private key (which is never disclosed to any other party), computes the
+public key and shares it.