DO NOT EDIT! This file is generated. See Makefile.
This library provides the cryptographic routines needed by an electronic voting client implemented in Javascript. It is documented in detail and considerable time has been invested in organizing the the code.
Although this library is fast, the goal is not to be as fast as possible, but to be fast enough and as clean and well documented as possible. M4 macros are used for both purposes.
The library is compiled from multiple files using M4 into a single properly formatted and indented file that encapsulates all functionality that should not be readily accessible. Users should not add any variables or functions to the namespaces.
This is not a general purpose library for cryptographic software. Please read the warnings below.
This library consists of a stack of the following modules:
verificatum.arithm.li is a raw multi-precision integer arithmetic module. This is essentially optimized in only two ways; memory allocation must be handled manually, and the inner-most so-called "muladd" loop is optimized. Apart from this, it is a relatively straightforward implementation of school book arithmetic. References are provided for all non-trivial algorithms.
verificatum.arithm.sli provides signed multi-precision integer arithmetic. This is a thin layer on top of verificatum.arithm.li along with a few extra basic routines are are easier to implement with signed arithmetic than without, e.g., the extended binary greatest common divisor algorithm.
verificatum.arithm.LargeInteger provides automatic memory allocation on top of verificatum.arithm.li and verificatum.arithm.sli.
verificatum.arithm.PGroup provides abstract classes that capture groups of prime order.
verificatum.arithm.ModPGroup provides prime order subgroups modulo primes. This is a wrapper of verificatum.arithm.LargeInteger using modular arithmetic that provides additional utility routines.
verificatum.arithm.ec provides a raw implementation of elliptic curves over prime order fields of Weierstrass form using a variant of Jacobi coordinates. This uses the standard formulas, but on top of verificatum.arithm.sli (not verificatum.arithm.LargeInteger).
verificatum.arithm.ECqPGroup provides elliptic curve groups over prime order fields of Weierstrass form using a variant of Jacobi coordinates. In particular the standard curves of this form. This is a wrapper of verificatum.arithm.ec that provides automatic memory allocation and additional utility routines.
verificatum.arithm.PField implements a prime order field that may be thought of as the "exponents of a group". This is a wrapper of verificatum.arithm.LargeInteger, where computations take place modulo the order of the group. It also provides additional utility routines.
verificatum.arithm.PPGroup implements a product group that combines multiple groups into one to simplify computations over multiple group elements. The resulting group elements are basically glorified lists with routines that iterate over the individual elements. It generalizes both the arithmetic and utility functions to product groups.
verificatum.arithm.PPRing implements the product ring of a product group. We may think of this as the "ring of exponents". Similarly to product groups its elements are glorified lists of field elements along with arithmetic and utility routines that iterate over these elements.
A notable pattern used in the code is using static variables in functions, where a variable is static if it survives function invocations. This is implemented using encapsulation with immediate functions. Static variables are re-sized as needed, but for our application this rarely happens, so effectively we have automatic light-weight memory allocation.
Some classes can be optionally included in the library. See
BUILDING.md and Makefile for more
information. Testing if a class is included is done using
typeof, e.g., the following is a
boolean that is true if and only if the class ECqPGroup was
included in the build.
typeof verificatum.arithm.ECqPGroup !== "undefined"
The function verificatum.util.ofType is robust as
long as the second parameter is either a string literal or a type.
To keep things consistent, we only use
typedef variable === "undefined" when checking for
undefined parameters to functions.
WARNING! Please read the following instructions carefully. Failure to do so may result in a completely insecure installation.
You should NOT use this library unless you have verified the following:
Run all tests. JavaScript is a language with a heterogeneous set of available interpreters/engines. We have done our best to only use the most standard features, but we can not exclude the possibility that there are issues on any particular platform, since there are simply too many and they are constantly evolving.
Verify that the random source accessible from
verificatum.crypto.RandomDevice is secure.
A number of natural approaches are possible if this is not the
case. We avoid all of these until we have a clear reason, since
they bring additional complexity and potential incompatibilities
and security issues in themselves.
WARNING! Please read the following instructions carefully. Failure to do so may result in a completely insecure installation.
This library does not protect against side channel attacks. Thus, this is not a general purpose cryptographic library, but it is secure in electronic voting clients because of two reasons:
The system is currently only used for encryption. Thus, random encryption exponents of the El Gamal cryptosystem are only used once. This effectively curtails any cache or timing attacks due to the lack of statistics.
A human being determines when encryption takes place. Thus, the adversary can not influence when an encryption takes place with sufficient granularity to execute repeated attacks.
This should be compared with, e.g., a TLS server that handles repeated requests from a potential adversary using a fixed secret key.
Our software handles special curve points correctly and all inputs are verified to belong to the right domain before processing. This turns out to be particularly important for the mix-nets that process the ciphertexts formed using this library.
However, we naturally welcome the inclusion of non-NIST curves that are more resistant against side channel attacks. For more information we recommend, e.g., Daniel J. Bernstein and Tanja Lange. SafeCurves: choosing safe curves for elliptic-curve cryptography, (accessed 1 December 2014).
WARNING! Please read the following instructions carefully. Failure to do so may result in a completely insecure installation.
This library does not on its own protect against attacks against the browser or the operating system. A short and non-exhaustive list of threats includes:
Virus that corrupts the client as a whole.
Cross-scripting attacks.
Functional, memory, resource leakage between plugins or interpreters of the browser.
Weak source of randomness provided by the browser. This includes attempts to provide randomness by observing mouse movements (less relevant in a world with touch screens), or accessing external sites with built-in crypto libraries to harvest randomness.
It is impossible to fully protect a client against such attacks. We can only reduce the risk in different ways.
However, electronic voting systems typically provide mechanisms at the cryptographic protocol level to allow the voter or auditors to verify that the right vote is encrypted.
Thus, these risks are "only" relevant for privacy if the rest of the system is implemented properly.