From 3bd70991d4c72647882a74d0222aa12ac9cba5d0 Mon Sep 17 00:00:00 2001 From: Mamy Ratsimbazafy Date: Mon, 24 Feb 2020 10:50:19 +0100 Subject: [PATCH] reorg the codebase + add/update READMEs in folders with research (#12) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * 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 | 1 + constantine/{math => arithmetic}/README.md | 2 +- .../{math => arithmetic}/bigints_checked.nim | 0 .../{math => arithmetic}/bigints_raw.nim | 0 .../{math => arithmetic}/finite_fields.nim | 0 .../{math => arithmetic}/precomputed.nim | 0 constantine/config/README.md | 5 ++ constantine/config/curves.nim | 2 +- constantine/config/curves_parser.nim | 2 +- constantine/elliptic/README.md | 6 +- constantine/hash_to_curve/README.md | 32 ++++++++ constantine/io/README.md | 8 +- constantine/io/io_bigints.nim | 2 +- constantine/io/io_fields.nim | 2 +- constantine/isogeny/README.md | 15 ++++ constantine/pairing/README.md | 40 +++++++-- constantine/primitives/README.md | 7 +- constantine/signatures/README.md | 15 +++- constantine/tower_field_extensions/README.md | 82 +++++++++++++++++++ tests/test_bigints.nim | 2 +- tests/test_bigints_multimod.nim | 2 +- tests/test_bigints_vs_gmp.nim | 2 +- tests/test_finite_fields.nim | 2 +- tests/test_finite_fields_powinv.nim | 2 +- tests/test_finite_fields_vs_gmp.nim | 2 +- tests/test_io_bigints.nim | 2 +- tests/test_io_fields.nim | 2 +- 27 files changed, 207 insertions(+), 30 deletions(-) rename constantine/{math => arithmetic}/README.md (89%) rename constantine/{math => arithmetic}/bigints_checked.nim (100%) rename constantine/{math => arithmetic}/bigints_raw.nim (100%) rename constantine/{math => arithmetic}/finite_fields.nim (100%) rename constantine/{math => arithmetic}/precomputed.nim (100%) create mode 100644 constantine/config/README.md create mode 100644 constantine/hash_to_curve/README.md create mode 100644 constantine/isogeny/README.md create mode 100644 constantine/tower_field_extensions/README.md diff --git a/README.md b/README.md index 97ada4d..59c183d 100644 --- a/README.md +++ b/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 diff --git a/constantine/math/README.md b/constantine/arithmetic/README.md similarity index 89% rename from constantine/math/README.md rename to constantine/arithmetic/README.md index b57874f..081ea25 100644 --- a/constantine/math/README.md +++ b/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) diff --git a/constantine/math/bigints_checked.nim b/constantine/arithmetic/bigints_checked.nim similarity index 100% rename from constantine/math/bigints_checked.nim rename to constantine/arithmetic/bigints_checked.nim diff --git a/constantine/math/bigints_raw.nim b/constantine/arithmetic/bigints_raw.nim similarity index 100% rename from constantine/math/bigints_raw.nim rename to constantine/arithmetic/bigints_raw.nim diff --git a/constantine/math/finite_fields.nim b/constantine/arithmetic/finite_fields.nim similarity index 100% rename from constantine/math/finite_fields.nim rename to constantine/arithmetic/finite_fields.nim diff --git a/constantine/math/precomputed.nim b/constantine/arithmetic/precomputed.nim similarity index 100% rename from constantine/math/precomputed.nim rename to constantine/arithmetic/precomputed.nim diff --git a/constantine/config/README.md b/constantine/config/README.md new file mode 100644 index 0000000..75266ba --- /dev/null +++ b/constantine/config/README.md @@ -0,0 +1,5 @@ +# Common configuration + +- Low-level logical and physical word definitions +- Elliptic curve declarations +- Cipher suites diff --git a/constantine/config/curves.nim b/constantine/config/curves.nim index db45200..e4ea71c 100644 --- a/constantine/config/curves.nim +++ b/constantine/config/curves.nim @@ -11,7 +11,7 @@ import macros, # Internal ./curves_parser, ./common, - ../math/[precomputed, bigints_checked] + ../arithmetic/[precomputed, bigints_checked] # ############################################################ diff --git a/constantine/config/curves_parser.nim b/constantine/config/curves_parser.nim index 7d80550..1814971 100644 --- a/constantine/config/curves_parser.nim +++ b/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. diff --git a/constantine/elliptic/README.md b/constantine/elliptic/README.md index 93913b4..cdb900e 100644 --- a/constantine/elliptic/README.md +++ b/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 diff --git a/constantine/hash_to_curve/README.md b/constantine/hash_to_curve/README.md new file mode 100644 index 0000000..d74377b --- /dev/null +++ b/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 diff --git a/constantine/io/README.md b/constantine/io/README.md index 9b5e234..d13da22 100644 --- a/constantine/io/README.md +++ b/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 diff --git a/constantine/io/io_bigints.nim b/constantine/io/io_bigints.nim index a7e437e..102bd48 100644 --- a/constantine/io/io_bigints.nim +++ b/constantine/io/io_bigints.nim @@ -12,7 +12,7 @@ import ../primitives/constant_time, - ../math/bigints_checked, + ../arithmetic/bigints_checked, ../config/common # ############################################################ diff --git a/constantine/io/io_fields.nim b/constantine/io/io_fields.nim index 8bc236e..e577a25 100644 --- a/constantine/io/io_fields.nim +++ b/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: [].} diff --git a/constantine/isogeny/README.md b/constantine/isogeny/README.md new file mode 100644 index 0000000..0a5b880 --- /dev/null +++ b/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 diff --git a/constantine/pairing/README.md b/constantine/pairing/README.md index 9091c20..f96ad8e 100644 --- a/constantine/pairing/README.md +++ b/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 diff --git a/constantine/primitives/README.md b/constantine/primitives/README.md index 8d6d2b2..c4374f8 100644 --- a/constantine/primitives/README.md +++ b/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 diff --git a/constantine/signatures/README.md b/constantine/signatures/README.md index e34e465..5e2fdf0 100644 --- a/constantine/signatures/README.md +++ b/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 diff --git a/constantine/tower_field_extensions/README.md b/constantine/tower_field_extensions/README.md new file mode 100644 index 0000000..d46b1c2 --- /dev/null +++ b/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 diff --git a/tests/test_bigints.nim b/tests/test_bigints.nim index 3d89c68..7dc424b 100644 --- a/tests/test_bigints.nim +++ b/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 diff --git a/tests/test_bigints_multimod.nim b/tests/test_bigints_multimod.nim index c7bc856..84baa9c 100644 --- a/tests/test_bigints_multimod.nim +++ b/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() = diff --git a/tests/test_bigints_vs_gmp.nim b/tests/test_bigints_vs_gmp.nim index b237728..f11840b 100644 --- a/tests/test_bigints_vs_gmp.nim +++ b/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 diff --git a/tests/test_finite_fields.nim b/tests/test_finite_fields.nim index d9654ac..73eac84 100644 --- a/tests/test_finite_fields.nim +++ b/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 diff --git a/tests/test_finite_fields_powinv.nim b/tests/test_finite_fields_powinv.nim index 3c710b8..5d5f815 100644 --- a/tests/test_finite_fields_powinv.nim +++ b/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 diff --git a/tests/test_finite_fields_vs_gmp.nim b/tests/test_finite_fields_vs_gmp.nim index 8ff77a0..942a867 100644 --- a/tests/test_finite_fields_vs_gmp.nim +++ b/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 diff --git a/tests/test_io_bigints.nim b/tests/test_io_bigints.nim index b1de2b2..0ae021d 100644 --- a/tests/test_io_bigints.nim +++ b/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 diff --git a/tests/test_io_fields.nim b/tests/test_io_fields.nim index 5ead349..fed1cfe 100644 --- a/tests/test_io_fields.nim +++ b/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