reorg the codebase + add/update READMEs in folders with research (#12)

* reorg the codebase + add/update READMEs in folders with research

* fix readme

* update pairing implementation papers

* Seperate hash-to-curve in its own folder, distinguish between norms, research and presentations

* Better markdown line breaks

* Add in-depth analysis of towers of extension fields for BN curve

* Fix Colm Ó hÉigeartaigh name and add Hash-to-Curve reference

README.md

@@ -26,6 +26,7 @@ The library focuses on following properties:
 - constant-time (not leaking secret data via side-channels)
 - generated code size, datatype size and stack usage
 - performance
+
 in this order
 
 ## Security

constantine/arithmetic/README.md

@@ -1,5 +1,5 @@
 # BigInt and Finite Field Arithmetic
 
 This folder contains the implementation of
-- big integer
+- big integers
 - finite field arithmetic (i.e. modular arithmetic)

constantine/config/README.md

@@ -0,0 +1,5 @@
+# Common configuration
+
+- Low-level logical and physical word definitions
+- Elliptic curve declarations
+- Cipher suites

constantine/config/curves.nim

@@ -11,7 +11,7 @@ import
   macros,
   # Internal
   ./curves_parser, ./common,
-  ../math/[precomputed, bigints_checked]
+  ../arithmetic/[precomputed, bigints_checked]
 
 
 # ############################################################

constantine/config/curves_parser.nim

@@ -10,7 +10,7 @@ import
   # Standard library
   macros,
   # Internal
-  ../io/io_bigints, ../math/bigints_checked
+  ../io/io_bigints, ../arithmetic/bigints_checked
 
 # Macro to parse declarative curves configuration.
 

constantine/elliptic/README.md

@@ -1,7 +1,9 @@
 # Elliptic Curves
 
-This folder will hold the implementation of elliptic curves.
+This folder will hold the implementation of elliptic curves arithmetic
 
 ## References
 
-- Pairing-Friendly Curves https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-00#section-2.1
+- Pairing-Friendly Curves\
+  (Draft, expires May 4, 2020)\
+  https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-00#section-2.1

constantine/hash_to_curve/README.md

@@ -0,0 +1,32 @@
+# Hashing to Elliptic Curves
+
+## References
+
+### Normative references
+
+- Hashing to Elliptic Curve\
+  (Draft, expires May 5, 2020)\
+  https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-05 \
+  https://github.com/cfrg/draft-irtf-cfrg-hash-to-curve
+
+### Research
+
+- Fast Hashing to $G_2$ on Pairing-Friendly Curves \
+  Michael Scott, Naomi Benger, Manuel Charlemagne, Luis J. Dominguez Perez, Ezekiel J. Kachisa, 2009\
+  https://doi.org/10.1007/978-3-642-03298-1_8
+
+- Faster Hashing to $G_2$\
+  Laura Fuentes-Castañeda, Edward Knapp, Francisco Rodríguez-Henríquez, 2011\
+  https://link.springer.com/chapter/10.1007%2F978-3-642-28496-0_25
+
+- Indifferentiable Hashing to Barreto–Naehrig Curves\
+  Pierre-Alain Fouque, Mehdi Tibouchi, 2012\
+  https://hal.inria.fr/hal-01094321/file/FT12.pdf
+
+- Hashing to $G_2$ on BLS pairing-friendly curves\
+  Alessandro Budroni, Federico Pintore, 2019\
+  https://doi.org/10.1145/3313880.3313884
+
+- Fast and simple constant-time hashing to the BLS12-381 elliptic curve\
+  Riad S. Wahby and Dan Boneh, 2019\
+  https://eprint.iacr.org/2019/403

constantine/io/README.md

@@ -1,7 +1,9 @@
-# I/O and serialization
+# I/O, serialization, encoding/decoding
 
 ## References
 
-- Standards for Efficient Cryptography Group (SECG),
-  "SEC 1: Elliptic Curve Cryptography", May 2009,
+### Normative references
+
+- Standards for Efficient Cryptography Group (SECG),\
+  "SEC 1: Elliptic Curve Cryptography", May 2009,\
   http://www.secg.org/sec1-v2.pdf

constantine/io/io_bigints.nim

@@ -12,7 +12,7 @@
 
 import
   ../primitives/constant_time,
-  ../math/bigints_checked,
+  ../arithmetic/bigints_checked,
   ../config/common
 
 # ############################################################

constantine/io/io_fields.nim

@@ -9,7 +9,7 @@
 import
   ./io_bigints,
   ../config/curves,
-  ../math/[bigints_checked, finite_fields]
+  ../arithmetic/[bigints_checked, finite_fields]
 
 # No exceptions allowed
 {.push raises: [].}

constantine/isogeny/README.md

@@ -0,0 +1,15 @@
+# Isogeny-based Cryptography
+
+This folder will hold the implementations of isogeny-based cryptography.
+
+The initial focus will be the isogeny maps necessary to implement
+hashing to elliptic curve
+
+## References
+
+### Normative references
+
+- Hashing to Elliptic Curve\
+  (Draft, expires May 5, 2020)\
+  https://tools.ietf.org/html/draft-irtf-cfrg-hash-to-curve-05 \
+  https://github.com/cfrg/draft-irtf-cfrg-hash-to-curve

constantine/pairing/README.md

@@ -2,20 +2,42 @@
 
 ## References
 
-- Pairing-Friendly Curves
-
-  IETF Draft Specification (expires May 2020)
+### Normative references
 
+- Pairing-Friendly Curves\
+  IETF Draft Specification (expires May 2020)\
   https://tools.ietf.org/html/draft-irtf-cfrg-pairing-friendly-curves-00#ref-KB16
 
-- Multiplication and Squaring on Pairing-Friendly Fields
+### Research
 
-  Devigili et al
+- On the Implementation of Pairing-based Cryptosystems\
+  PhD Thesis\
+  Ben Lynn, 2007\
+  https://crypto.stanford.edu/pbc/thesis.pdf
 
-  https://eprint.iacr.org/2006/471
+- Pairings for beginners\
+  Craig Costello, 2012 (?)\
+  http://www.craigcostello.com.au/pairings/PairingsForBeginners.pdf
 
-- Constructing Tower Extensions for the implementation of Pairing-Based Cryptography
+- Fast Formulas for Computing Cryptographic Pairings\
+  PhD Thesis\
+  Craig Costello, 2012\
+  https://eprints.qut.edu.au/61037/1/Craig_Costello_Thesis.pdf
 
-  Benger et al
+- Efficient Implementations of Pairing-Based Cryptography on Embedded Systems\
+  Master Thesis\
+  Rajeev Verma, 2015\
+  https://scholarworks.rit.edu/cgi/viewcontent.cgi?referer=&httpsredir=1&article=10083&context=theses
+  https://github.com/rajeevakarv/FiniteFieldComputations
 
-  https://eprint.iacr.org/2009/556
+
+- A taxonomy of pairings, their security, their complexity\
+  Razvan Barbulescu, Nadia El Mrabet, and Loubna Ghammam, 2019\
+  https://hal.archives-ouvertes.fr/hal-02129868/file/2019-485.pdf
+
+### Presentations
+
+- Introduction to pairings\
+  ECC Summer School\
+  Diego F. Aranha, 2017\
+  https://ecc2017.cs.ru.nl/slides/ecc2017school-aranha.pdf

constantine/primitives/README.md

@@ -1,3 +1,8 @@
 # Constant-time primitives
 
-This folder holds the constant-time primitives
+This folder holds:
+
+- the constant-time primitives, implemented as distinct types
+  to have the compiler enforce proper usage
+- extended precision multiplication and division primitives
+- assembly primitives

constantine/signatures/README.md

@@ -11,6 +11,17 @@ Note: The BLS signature scheme should not be confused
 
 ## References
 
-### ECDSA
+### Normative references
 
-- 
+#### ECDSA
+
+- RFC 6979 Deterministic Usage of the Digital Signature Algorithm (DSA) and
+           Elliptic Curve Digital Signature Algorithm (ECDSA)\
+  https://tools.ietf.org/html/rfc6979
+
+#### BLS signatures
+
+- BLS Signature Scheme\
+  (Draft, expires Feb 9, 2020)\
+  https://tools.ietf.org/html/draft-irtf-cfrg-bls-signature-00  \
+  https://github.com/cfrg/draft-irtf-cfrg-bls-signature

constantine/tower_field_extensions/README.md

@@ -0,0 +1,82 @@
+# Tower Extensions of Finite Fields
+
+## Overview
+
+From Ben Edgington, https://hackmd.io/@benjaminion/bls12-381
+
+> ### Field extensions
+>
+> Field extensions are fundamental to elliptic curve pairings. The "12" is BLS12-381 is not only the embedding degree, it is also (relatedly) the degree of field extension that we will need to use.
+>
+> The field $F_q$ can be thought of as just the integers modulo $q$: $0,1,...,q-1$. But what kind of beast is $F_{q^{12}}$, the twelfth extension of $F_q$?
+>
+> I totally failed to find any straightforward explainers of field extensions out there, so here's my attempt after wrestling with this for a while.
+>
+> Let's construct an $F_{q^2}$, the quadratic extension of $F_q$. In $F_{q^2}$ we will represent field elements as first-degree polynomials like $a_0 + a_1x$, which we can write more concisely as $(a_0, a_1)$ if we wish.
+>
+> Adding two elements is easy: $(a, b) + (c, d) =$$a + bx + c + dx =$$(a+c) + (b+d)x =$$(a+c, b+d)$. We just need to be sure to reduce $a+c$ and $b+d$ modulo $q$.
+>
+> What about multiplying? $(a, b) \times (c, d) =$$(a + bx)(c + dx) =$$ac + (ad+bc)x+ bdx^2 =$$???$. Oops - what are we supposed to do with that $x^2$ coefficient?
+>
+> We need a rule for reducing polynomials so that they have a degree less than two. In this example we're going to take $x^2 + 1 = 0$ as our rule, but we could make other choices. There are only two rules about our rule^[Our rule is "an extension field modular reduction" (terminology from [here](https://www.emsec.ruhr-uni-bochum.de/media/crypto/veroeffentlichungen/2015/03/26/crypto98rc9.pdf)).]:
+>  1. it must be a degree $k$ polynomial, where $k$ is our extension degree, $2$ in this case; and
+>  2. it must be [irreducible](https://en.wikipedia.org/wiki/Irreducible_polynomial) in the field we are extending. That means it must not be possible to factor it into two or more lower degree polynomials.
+>
+> Applying our rule, by substituting $x^2 = -1$, gives us the final result $(a, b) \times (c, d) =$$ac + (ad+bc)x + bdx^2 =$$(ac-bd) + (ad+bc)x =$$(ac-bd, ad+bc)$. This might look a little familiar from complex arithmetic: $(a+ib) \times (c+id) =$$(ac-bd) + (ad+bc)i$. This is not a coincidence! The complex numbers are a quadratic extension of the real numbers.
+>
+> Complex numbers can't be extended any further because there are [no irreducible polynomials over the complex numbers](https://en.wikipedia.org/wiki/Fundamental_theorem_of_algebra). But for finite fields, if we can find an irreducible $k$-degree polynomial in our field $F_q$, and we often can, then we are able to extend the field to $F_{q^k}$, and represent the elements of the extended field as degree $k-1$ polynomials, $a_0 + a_1x +$$...$$+ a_{k-1}x^{k-1}$. We can represent this compactly as $(a_0,...,a_{k-1})$, as long as we remember that there may be some very funky arithmetic going on.
+>
+> Also worth noting is that modular reductions like this (our reduction rule) can be chosen so that they play nicely with the twisting operation.
+>
+> In practice, large extension fields like $F_{q^{12}}$ are implemented as towers of smaller extensions. That's an implementation aspect, so I've put it in the more practical section [below](#Extension-towers).
+>
+> ### Extension towers
+>
+> Recall our discussion of [field extensions](#Field-extensions)? In practice, rather than implementing a massive 12th-degree extension directly, it is more efficient to build it up from smaller extensions: [a tower of extensions](https://eprint.iacr.org/2009/556.pdf).
+>
+> For BLS12-381, the $F_{q^{12}}$ field is implemented as a quadratic (degree two) extension, on top of a cubic (degree three) extension, on top of a quadratic extension of $F_q$.
+>
+> As long as the modular reduction polynomial (our reduction rule) is irreducible (can't be factored) in the field being extended at each stage, then this all works out fine.
+>
+> [Specifically](https://github.com/zkcrypto/pairing/tree/master/src/bls12_381):
+>
+>   1. $F_{q^2}$ is constructed as $F_q(u) / (u^2 - \beta)$ where $\beta = -1$.
+>   2. $F_{q^6}$ is constructed as $F_{q^2}(v) / (v^3 - \xi)$ where $\xi = u + 1$.
+>   3. $F_{q^{12}}$ is constructed as $F_{q^6}(w) / (w^2 - \gamma)$ where $\gamma = v$
+>
+> Interpreting these in terms of our previous explantation:
+>   1. We write elements of the $F_{q^2}$ field as first degree polynomials in $u$, with coefficients from $F_q$, and apply the reduction rule $u^2 + 1 = 0$, which is irreducible in $F_q$.
+>       - an element of $F_{q^2}$ looks like $a_0 + a_1u$ where $a_j \in F_q$.
+>   3. We write elements of the $F_{q^6}$ field as second degree polynomials in $v$, with coefficients from the $F_{q^2}$ field we just constructed, and apply the reduction rule $v^3 - (u + 1) = 0$, which is irreducible in $F_{q^2}$.
+>       - an element of $F_{q^6}$ looks like $b_0 + b_1v + b_2v^2$ where $b_j \in F_{q^2}$.
+>   4. We write elements of the $F_{q^{12}}$ field as first degree polynomials in $w$, with coefficients from the $F_{q^6}$ field we just constructed, and apply the reduction rule $w^2 - v = 0$, which is irreducible in $F_{q^6}$.
+>       - an element of $F_{q^{12}}$ looks like $c_0 + c_1w$ where $c_j \in F_{q^6}$.
+>
+> This towered extension can replace the direct extension as a basis for pairings, and when well-implemented can save a huge amount of arithmetic when multiplying $F_{q^{12}}$ points. See [Pairings for Beginners](http://www.craigcostello.com.au/pairings/PairingsForBeginners.pdf) section 7.3 for a full discussion of the advantages.
+
+
+## References
+
+### Research
+
+- Optimal Extension Fields for Fast Arithmetic in Public-Key Algorithms\
+  Daniel V. Bailey and Christof Paar, 1998\
+  https://www.emsec.ruhr-uni-bochum.de/media/crypto/veroeffentlichungen/2015/03/26/crypto98rc9.pdf
+
+- Multiplication and Squaring on Pairing-Friendly Fields\
+  Augusto Jun Devegili and Colm Ó hÉigeartaigh and Michael Scott and Ricardo Dahab, 2006\
+  https://eprint.iacr.org/2006/471
+
+- Constructing Tower Extensions for the implementation of Pairing-Based Cryptography\
+  Naomi Benger and Michael Scott, 2009\
+  https://eprint.iacr.org/2009/556
+
+- Choosing and generating parameters for low level pairing implementation on BN curves\
+  Sylvain Duquesne and Nadia El Mrabet and Safia Haloui and Franck Rondepierre, 2015\
+  https://eprint.iacr.org/2015/1212
+
+### Presentations
+
+- BLS12-381 For The Rest Of Us\
+  Ben Edgington, 2019\
+  https://hackmd.io/@benjaminion/bls12-381

tests/test_bigints.nim

@@ -8,7 +8,7 @@
 
 import  unittest, random, strutils,
         ../constantine/io/io_bigints,
-        ../constantine/math/bigints_checked,
+        ../constantine/arithmetic/bigints_checked,
         ../constantine/config/common,
         ../constantine/primitives/constant_time
 

tests/test_bigints_multimod.nim

@@ -11,7 +11,7 @@ import
   unittest, random, strutils,
   # Third-party
   ../constantine/io/io_bigints,
-  ../constantine/math/[bigints_raw, bigints_checked],
+  ../constantine/arithmetic/[bigints_raw, bigints_checked],
   ../constantine/primitives/constant_time
 
 proc main() =

tests/test_bigints_vs_gmp.nim

@@ -13,7 +13,7 @@ import
   gmp, stew/byteutils,
   # Internal
   ../constantine/io/io_bigints,
-  ../constantine/math/[bigints_raw, bigints_checked],
+  ../constantine/arithmetic/[bigints_raw, bigints_checked],
   ../constantine/primitives/constant_time
 
 # We test up to 1024-bit, more is really slow

tests/test_finite_fields.nim

@@ -7,7 +7,7 @@
 # at your option. This file may not be copied, modified, or distributed except according to those terms.
 
 import  unittest, random,
-        ../constantine/math/finite_fields,
+        ../constantine/arithmetic/finite_fields,
         ../constantine/io/io_fields,
         ../constantine/config/curves
 

tests/test_finite_fields_powinv.nim

@@ -7,7 +7,7 @@
 # at your option. This file may not be copied, modified, or distributed except according to those terms.
 
 import  unittest, random,
-        ../constantine/math/[bigints_checked, finite_fields],
+        ../constantine/arithmetic/[bigints_checked, finite_fields],
         ../constantine/io/io_fields,
         ../constantine/config/curves
 

tests/test_finite_fields_vs_gmp.nim

@@ -13,7 +13,7 @@ import
   gmp, stew/byteutils,
   # Internal
   ../constantine/io/[io_bigints, io_fields],
-  ../constantine/math/[finite_fields, bigints_checked],
+  ../constantine/arithmetic/[finite_fields, bigints_checked],
   ../constantine/primitives/constant_time,
   ../constantine/config/curves
 

tests/test_io_bigints.nim

@@ -9,7 +9,7 @@
 import  unittest, random,
         ../constantine/io/io_bigints,
         ../constantine/config/common,
-        ../constantine/math/bigints_checked
+        ../constantine/arithmetic/bigints_checked
 
 randomize(0xDEADBEEF) # Random seed for reproducibility
 type T = BaseType

tests/test_io_fields.nim

@@ -10,7 +10,7 @@ import  unittest, random,
         ../constantine/io/[io_bigints, io_fields],
         ../constantine/config/curves,
         ../constantine/config/common,
-        ../constantine/math/[bigints_checked, finite_fields]
+        ../constantine/arithmetic/[bigints_checked, finite_fields]
 
 randomize(0xDEADBEEF) # Random seed for reproducibility
 type T = BaseType